CD ROM Paradise Collection 4

home *** CD-ROM | disk | FTP | other *** search

/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / system / tsx420a.zip / BBS.DOC < prev next >

Wrap

Text File | 1994-11-02 | 587.3 KB | 12,173 lines

T S X -- B B S Multi-Line Bulletin Board System Copyright (c) 1994 S&H Computer Systems, Inc. 1027 17th Avenue South Nashville, TN 37212 615-327-3670 71333.27@compuserve.com TSX-BBS is a full 32-bit, multi-user bulletin board system that runs in conjunction with the TSX-32 and TSX-Lite operating systems. TSX-BBS provides a full featured multi-user bulletin board environment complete with file library, discussion forums (Fido, Usenet, etc.), real-time conferencing (chat), E-mail, and file upload/download. TSX-BBS also provides options for direct access to Internet using Telnet FTP. TSX-BBS requires the TSX-32 or TSX-Lite operating systems. TSX-Lite requires a 386, 486, or Pentium computer system with at least 8Mb of memory and 15Mb of free disk space. VGA and MDA display adapters are supported along with a variety of disk adapters. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 A Multi-Line System . . . . . . . . . . . . . . . . . . . . 1 1.2 Super System Capacity . . . . . . . . . . . . . . . . . . . 1 1.3 Reliable, Non-stop Operation . . . . . . . . . . . . . . . 2 1.4 A Sysop's Dream . . . . . . . . . . . . . . . . . . . . . . 2 1.5 Door Program Support . . . . . . . . . . . . . . . . . . . 2 1.6 Flexibility is the Key . . . . . . . . . . . . . . . . . . 3 1.7 Use TPL to Extend Your System . . . . . . . . . . . . . . . 4 1.8 File Libraries . . . . . . . . . . . . . . . . . . . . . . 4 1.9 Personal File Workspace . . . . . . . . . . . . . . . . . . 5 1.10 Newsgroups and Discussion Forums . . . . . . . . . . . . . 5 1.11 E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.12 Direct Internet Access . . . . . . . . . . . . . . . . . . 6 1.13 Incoming SLIP connections . . . . . . . . . . . . . . . . 7 1.14 On-line "Chat" . . . . . . . . . . . . . . . . . . . . . . 7 1.15 TSX-BBS System Security . . . . . . . . . . . . . . . . . 7 1.16 System Control . . . . . . . . . . . . . . . . . . . . . . 8 2. Installing TSX-BBS . . . . . . . . . . . . . . . . . . . . . . 9 2.1 Demonstration, Shareware Version of TSX-BBS . . . . . . . . 9 2.2 TSX-32 System Generation Considerations . . . . . . . . . . 9 2.2.1 General System Parameters . . . . . . . . . . . . . . . 10 2.2.2 Serial Line Parameters . . . . . . . . . . . . . . . . 10 2.3 Modem Setup . . . . . . . . . . . . . . . . . . . . . . . . 13 2.4 TSX-BBS Installation . . . . . . . . . . . . . . . . . . . 15 2.4.1 Installing a Commercial System . . . . . . . . . . . . 15 2.4.2 Installing the Demonstration System . . . . . . . . . . 15 2.5 TSX-BBS Initialization . . . . . . . . . . . . . . . . . . 16 2.5.1 General Setup . . . . . . . . . . . . . . . . . . . . . 16 2.5.2 User Authorization . . . . . . . . . . . . . . . . . . 17 2.5.3 Scheduled Utilities . . . . . . . . . . . . . . . . . . 18 2.5.4 File Library Setup . . . . . . . . . . . . . . . . . . 18 2.5.4.1 File Upload Area . . . . . . . . . . . . . . . . . 19 2.5.5 Discussion Forum Initialization . . . . . . . . . . . . 20 2.5.6 Local Logon . . . . . . . . . . . . . . . . . . . . . . 20 2.5.7 Menu Customization . . . . . . . . . . . . . . . . . . 20 3. Color and Substitution Operators . . . . . . . . . . . . . . . 21 3.1 Color operators . . . . . . . . . . . . . . . . . . . . . . 21 3.2 Substitution operators . . . . . . . . . . . . . . . . . . 24 4. Conditional Expressions . . . . . . . . . . . . . . . . . . . 31 4.1 Built-in Privileges . . . . . . . . . . . . . . . . . . . . 32 4.2 Sysop-defined Privileges . . . . . . . . . . . . . . . . . 33 4.3 System Variables . . . . . . . . . . . . . . . . . . . . . 33 4.4 Conditional Expressions in Menus and Text . . . . . . . . . 35 i Contents ii 5. Menu Compiler . . . . . . . . . . . . . . . . . . . . . . . . 37 5.1 Using the Menu Compiler . . . . . . . . . . . . . . . . . . 37 5.2 Introductory Example . . . . . . . . . . . . . . . . . . . 37 5.3 $name -- Activity name for menu . . . . . . . . . . . . . . 39 5.4 $hot -- Single character activation . . . . . . . . . . . . 39 5.5 $prompt -- Prompt string . . . . . . . . . . . . . . . . . 39 5.6 $display -- Display text for menu . . . . . . . . . . . . . 39 5.7 $item -- Action item . . . . . . . . . . . . . . . . . . . 41 5.7.1 key -- Character or command . . . . . . . . . . . . . . 41 5.7.2 if -- Conditional item . . . . . . . . . . . . . . . . 42 5.7.3 action -- Menu action . . . . . . . . . . . . . . . . . 42 5.7.3.1 Combined actions . . . . . . . . . . . . . . . . . 43 5.7.3.2 actname -- Set activity name . . . . . . . . . . . 43 5.7.3.3 autologoff -- Do count down and then logoff . . . . 43 5.7.3.4 bbsexit -- Exit from BBS to TSX . . . . . . . . . . 44 5.7.3.5 brfile -- Browse text file . . . . . . . . . . . . 44 5.7.3.6 chathandle -- Change chat handle . . . . . . . . . 44 5.7.3.7 chatjoin -- Join a chat group . . . . . . . . . . . 44 5.7.3.8 chatmake -- Create a chat group . . . . . . . . . . 44 5.7.3.9 chatuser -- List users in chat . . . . . . . . . . 44 5.7.3.10 datesearch -- Search for files by date . . . . . . 45 5.7.3.11 dirupload -- Upload files to a directory . . . . . 45 5.7.3.12 dispfile -- Display a file . . . . . . . . . . . . 45 5.7.3.13 display -- Display a string . . . . . . . . . . . 46 5.7.3.14 door -- Run door program . . . . . . . . . . . . . 46 5.7.3.15 download -- Download a file . . . . . . . . . . . 47 5.7.3.16 exit -- Exit from menus . . . . . . . . . . . . . 47 5.7.3.17 fallist -- Display file area list . . . . . . . . 47 5.7.3.18 falsearch -- Search file descriptions . . . . . . 47 5.7.3.19 fdllist -- List files in an FDL . . . . . . . . . 48 5.7.3.20 fdlsearch -- Search through file list . . . . . . 48 5.7.3.21 fdlupload -- Upload a file . . . . . . . . . . . . 48 5.7.3.22 fmpmenu -- Display file transfer protocol menu . . 49 5.7.3.23 fmpset -- Set file transfer protocol . . . . . . . 49 5.7.3.24 forumcheck -- Check for pending forum messages . . 49 5.7.3.25 frmalist -- Display alphabetic list of forums . . 49 5.7.3.26 frmdownload -- Downloaded selected messages . . . 50 5.7.3.27 frmenter -- Enter the forum name hierarchy . . . . 50 5.7.3.28 frmgetlist -- Download list of forums . . . . . . 51 5.7.3.29 frmslist -- Search for list of forums . . . . . . 51 5.7.3.30 frmentnum -- Enter a forum by number . . . . . . . 52 5.7.3.31 frmentname -- Enter a forum by name . . . . . . . 52 5.7.3.32 frmprefix -- Enter forum by name with prefix . . . 52 5.7.3.33 frmqwkman -- Manage QWK forum list . . . . . . . . 52 5.7.3.34 ftp -- Invoke Internet FTP File Transfer Program . 52 5.7.3.35 logoff -- Log off the BBS . . . . . . . . . . . . 53 5.7.3.36 logwrite -- Write message to BBS log file . . . . 53 5.7.3.37 mailabook -- Manage address book . . . . . . . . . 53 5.7.3.38 mailbrowse -- Browse message base . . . . . . . . 53 5.7.3.39 mailcheck -- Check for pending mail messages . . . 53 5.7.3.40 mailfile -- Manage filing cabinet . . . . . . . . 54 5.7.3.41 mailrecv -- Receive messages . . . . . . . . . . . 54 5.7.3.42 mailsend -- Send a message . . . . . . . . . . . . 54 5.7.3.43 mailsyn -- Manage synonymous names . . . . . . . . 54 5.7.3.44 mailsysop -- Send message to sysop . . . . . . . . 55 Contents iii 5.7.3.45 menu -- Call a menu . . . . . . . . . . . . . . . 55 5.7.3.46 menujump -- Jump to a menu . . . . . . . . . . . . 55 5.7.3.47 namesel -- Select files for download by name . . . 56 5.7.3.48 offcheck -- Confirm and then logoff . . . . . . . 56 5.7.3.49 offquiet -- Log off without message . . . . . . . 56 5.7.3.50 pagesysop -- Page the sysop . . . . . . . . . . . 56 5.7.3.51 pause -- Display a string and pause . . . . . . . 57 5.7.3.52 print -- Display a string . . . . . . . . . . . . 57 5.7.3.53 pws -- Manage personal file workspace . . . . . . 57 5.7.3.54 qwkcfg -- Set QWK configuration options . . . . . 57 5.7.3.55 qwkdownload -- Download QWK packet with messages . 57 5.7.3.56 qwkservices -- Select services . . . . . . . . . . 58 5.7.3.57 qwkupload -- Upload a QWK packet . . . . . . . . . 58 5.7.3.58 qwkread -- Read new messages from forums . . . . . 58 5.7.3.59 return -- Return from menu call . . . . . . . . . 58 5.7.3.60 setclass -- Change user class . . . . . . . . . . 58 5.7.3.61 tagdl -- Download currently tagged files . . . . . 59 5.7.3.62 tagedit -- Edit the list of tagged files . . . . . 59 5.7.3.63 telnet -- Invoke Telnet Internet program . . . . . 59 5.7.3.64 top -- Return to top level menu . . . . . . . . . 59 5.7.3.65 tpr -- Run TPL program . . . . . . . . . . . . . . 59 5.7.3.66 tsxcmd -- Execute TSX command . . . . . . . . . . 60 5.7.3.67 upload -- Upload a file . . . . . . . . . . . . . 60 5.7.3.68 useroptions -- Change user options . . . . . . . . 61 5.7.3.69 vote -- Enter voting system . . . . . . . . . . . 61 5.8 $initial -- Initial action item . . . . . . . . . . . . . . 61 6. Logon and Callback Procedures . . . . . . . . . . . . . . . . 62 6.1 Logon Procedure . . . . . . . . . . . . . . . . . . . . . . 62 6.2 Callback Verification . . . . . . . . . . . . . . . . . . . 63 6.2.1 Setting up Callback Verification . . . . . . . . . . . 65 6.2.2 The CALLBACK.DAT File . . . . . . . . . . . . . . . . . 65 6.2.2.1 STRIP command . . . . . . . . . . . . . . . . . . . 65 6.2.2.2 DIAL Command . . . . . . . . . . . . . . . . . . . 66 6.2.2.3 LDDIAL Command . . . . . . . . . . . . . . . . . . 66 6.2.2.4 LOCAL Command . . . . . . . . . . . . . . . . . . . 66 6.2.2.5 LD Command . . . . . . . . . . . . . . . . . . . . 67 6.2.2.6 EXCLUDE Command . . . . . . . . . . . . . . . . . . 67 6.3 Logon Using a Drop File . . . . . . . . . . . . . . . . . . 68 6.3.1 Drop File Format . . . . . . . . . . . . . . . . . . . 68 7. File Library . . . . . . . . . . . . . . . . . . . . . . . . . 71 7.1 File Categories and File Sets . . . . . . . . . . . . . . . 72 7.1.1 File Sets . . . . . . . . . . . . . . . . . . . . . . . 72 7.1.2 File Categories . . . . . . . . . . . . . . . . . . . . 73 7.1.3 Simple DOS Directories . . . . . . . . . . . . . . . . 73 7.2 Creating File Categories and File Sets . . . . . . . . . . 74 7.2.1 File category creation . . . . . . . . . . . . . . . . 74 7.2.2 File set creation . . . . . . . . . . . . . . . . . . . 75 7.3 Modifying File Descriptions and Attributes . . . . . . . . 77 7.4 Deleting Files, File Sets, and File Categories . . . . . . 77 7.5 Moving Files Between File Sets . . . . . . . . . . . . . . 78 7.6 Setting up Restricted File Areas . . . . . . . . . . . . . 78 7.7 Setting Up File Library Menus . . . . . . . . . . . . . . . 80 7.8 Search expressions . . . . . . . . . . . . . . . . . . . . 82 Contents iv 7.9 PCBoard DIR File to FDL File Converter . . . . . . . . . . 83 7.10 TBBS DIR File to FDL File Converter . . . . . . . . . . . 84 8. Personal File Workspace . . . . . . . . . . . . . . . . . . . 85 8.1 Temporary and Permanent Workspaces . . . . . . . . . . . . 85 8.2 Workspace Size Limits . . . . . . . . . . . . . . . . . . . 86 8.3 Workspace Directories . . . . . . . . . . . . . . . . . . . 87 8.4 Personal Workspace Management . . . . . . . . . . . . . . . 87 9. Discussion Forums and Newsgroups . . . . . . . . . . . . . . . 89 9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 89 9.2 Batch Addition and Deletion of Messages . . . . . . . . . . 90 9.3 How to expire messages in forums. . . . . . . . . . . . . . 91 9.4 Expiring messages; The Sweeper program FSWEEP . . . . . . . 92 9.4.1 Sweeper command options . . . . . . . . . . . . . . . . 93 9.4.2 Examples . . . . . . . . . . . . . . . . . . . . . . . 96 9.4.3 Scheduling the sweeper . . . . . . . . . . . . . . . . 96 9.5 Forum Identification and Naming Conventions . . . . . . . . 96 9.6 Forum Access Privileges . . . . . . . . . . . . . . . . . . 99 9.7 Forum Creation and Access Issues . . . . . . . . . . . . 100 9.7.1 Restricting the Creation of New Forums . . . . . . . 101 9.7.2 Previewing New Forums Before Users . . . . . . . . . 102 9.7.3 Example of New Forum Management . . . . . . . . . . . 102 9.7.4 New Forum Management Using Privilege Inheritance . . 103 9.8 The Forum Control Files and User Access Files . . . . . . 103 9.8.1 Forum Control and Data Files . . . . . . . . . . . . 104 9.8.2 The BBS:FTREE.DAT File . . . . . . . . . . . . . . . 104 9.8.3 The VFILEx.DAT files . . . . . . . . . . . . . . . . 104 9.9 Forum Log Files and the Forum Event Log . . . . . . . . . 105 9.9.1 FSUMMARY.LOG . . . . . . . . . . . . . . . . . . . . 105 9.9.2 FSWEEP.LOG . . . . . . . . . . . . . . . . . . . . . 106 9.9.3 FREJECT.LOG . . . . . . . . . . . . . . . . . . . . . 108 9.9.4 FSTAT.LOG . . . . . . . . . . . . . . . . . . . . . . 108 9.9.5 FNEW.LOG . . . . . . . . . . . . . . . . . . . . . . 108 9.9.6 FERROR.LOG . . . . . . . . . . . . . . . . . . . . . 109 9.9.7 The FBATCH event log . . . . . . . . . . . . . . . . 109 9.10 Classified Ads . . . . . . . . . . . . . . . . . . . . . 109 9.10.1 User interface issues . . . . . . . . . . . . . . . 110 9.10.2 Specification of Classified Ad Forums to the SYSOP Pr 110 10. Electronic Mail . . . . . . . . . . . . . . . . . . . . . . 112 10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 112 10.2 Message Bases and Routes . . . . . . . . . . . . . . . . 113 10.3 Scanners and Tossers . . . . . . . . . . . . . . . . . . 114 10.4 The Mail Sweeper . . . . . . . . . . . . . . . . . . . . 114 10.5 Managing local mail . . . . . . . . . . . . . . . . . . 115 10.6 Filing Cabinet . . . . . . . . . . . . . . . . . . . . . 115 10.7 Accessing Mail from Menus . . . . . . . . . . . . . . . 116 11. Censoring Messages . . . . . . . . . . . . . . . . . . . . 117 11.1 Word Censoring Facility . . . . . . . . . . . . . . . . 117 11.1.1 CENSOR.DAT File . . . . . . . . . . . . . . . . . . 117 11.1.2 Censor Control Privilege . . . . . . . . . . . . . . 119 12. Internet Access . . . . . . . . . . . . . . . . . . . . . . 120 Contents v 12.1 FTP -- File Transfer Program . . . . . . . . . . . . . . 121 12.2 Telnet -- Internet Terminal Session . . . . . . . . . . 123 12.3 Internet Mail (SMTP) . . . . . . . . . . . . . . . . . . 123 12.3.1 Introduction . . . . . . . . . . . . . . . . . . . . 123 12.3.2 Setting up Internet Mail . . . . . . . . . . . . . . 124 12.3.3 The Internet Scanner . . . . . . . . . . . . . . . . 124 12.3.4 The Internet Tosser . . . . . . . . . . . . . . . . 125 13. Chat . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 13.1 Discussion Groups . . . . . . . . . . . . . . . . . . . 127 13.2 Chat handles . . . . . . . . . . . . . . . . . . . . . . 127 13.3 Scrolling . . . . . . . . . . . . . . . . . . . . . . . 128 13.4 The chat user interface . . . . . . . . . . . . . . . . 129 13.4.1 Changing handle . . . . . . . . . . . . . . . . . . 129 13.4.2 User list . . . . . . . . . . . . . . . . . . . . . 129 13.4.3 Creating a discussion group . . . . . . . . . . . . 129 13.4.4 Joining an existing group . . . . . . . . . . . . . 130 13.4.5 Reading and writing chat messages . . . . . . . . . 130 13.4.6 Chat commands . . . . . . . . . . . . . . . . . . . 130 13.5 Colors . . . . . . . . . . . . . . . . . . . . . . . . . 131 13.6 The chat server . . . . . . . . . . . . . . . . . . . . 131 13.7 Chat menu options . . . . . . . . . . . . . . . . . . . 131 14. Door Programs . . . . . . . . . . . . . . . . . . . . . . . 133 14.1 Running Door Programs with TSX-BBS . . . . . . . . . . . 134 14.2 Terminal I/O from the door program . . . . . . . . . . . 134 14.3 Drop Files . . . . . . . . . . . . . . . . . . . . . . . 135 14.4 Setting up Menu Entries to Run Doors . . . . . . . . . . 136 14.5 Taming Door Programs . . . . . . . . . . . . . . . . . . 138 15. The SYSOP Program . . . . . . . . . . . . . . . . . . . . . 140 15.1 General Setup . . . . . . . . . . . . . . . . . . . . . 140 15.2 User Authorization . . . . . . . . . . . . . . . . . . . 142 15.2.1 Adding New Users . . . . . . . . . . . . . . . . . . 143 15.2.2 Modifying Users . . . . . . . . . . . . . . . . . . 144 15.2.3 Removing Users . . . . . . . . . . . . . . . . . . . 145 15.2.4 User Classes and Privileges . . . . . . . . . . . . 145 15.3 Scheduling Utilities . . . . . . . . . . . . . . . . . . 148 15.3.1 Introduction . . . . . . . . . . . . . . . . . . . . 148 15.3.2 What Can Be Scheduled . . . . . . . . . . . . . . . 148 15.3.3 The Schedule Browse Screen . . . . . . . . . . . . . 148 15.3.4 Modifying an Existing Schedule . . . . . . . . . . . 149 15.3.5 Adding a New Schedule . . . . . . . . . . . . . . . 150 15.3.6 Deleting a Schedule . . . . . . . . . . . . . . . . 150 15.4 Color Customization . . . . . . . . . . . . . . . . . . 151 15.5 Chat groups . . . . . . . . . . . . . . . . . . . . . . 153 15.6 Paging Control . . . . . . . . . . . . . . . . . . . . . 154 15.7 Handle Control . . . . . . . . . . . . . . . . . . . . . 155 15.8 Language files . . . . . . . . . . . . . . . . . . . . . 155 15.8.1 Introduction . . . . . . . . . . . . . . . . . . . . 155 15.8.2 Creating New Databases . . . . . . . . . . . . . . . 156 15.8.3 Assigning Languages to Users . . . . . . . . . . . . 156 15.8.4 Editing Phrase Entries . . . . . . . . . . . . . . . 157 15.8.5 Mini Menus . . . . . . . . . . . . . . . . . . . . . 158 15.9 Mail Configuration . . . . . . . . . . . . . . . . . . . 159 Contents vi 15.9.1 Managing message bases . . . . . . . . . . . . . . . 159 15.9.2 Specifying Fidonet configuration . . . . . . . . . . 160 15.9.3 Specifying Usenset configuration . . . . . . . . . . 160 15.10 Discussion Forum Setup and Control . . . . . . . . . . 160 15.10.1 Defining the Locations of Forum Control Files . . . 161 15.10.2 The Hierarchical, Alphabetic, and Search displays . 162 15.10.2.1 The Hierarchical Display . . . . . . . . . . . 162 15.10.2.2 The Alphabetic and Search Displays . . . . . . 164 15.10.3 Creating New Forums . . . . . . . . . . . . . . . . 165 15.10.4 Modifying Forum Privileges and Attributes . . . . . 167 15.10.5 Deleting a Forum . . . . . . . . . . . . . . . . . 168 15.10.6 Erasing All Messages from a Forum . . . . . . . . . 169 15.10.7 Miscellaneous Forum Functions . . . . . . . . . . . 170 15.10.7.1 Specifying New Forum Defaults Privileges . . . 170 15.10.7.2 Options for Classified Ads . . . . . . . . . . 171 15.10.7.3 Log File Options . . . . . . . . . . . . . . . 171 15.10.7.4 Displaying the Forum Event Log . . . . . . . . 171 15.10.7.5 Reset Log Files and Event Log . . . . . . . . . 171 15.10.7.6 Creating the User Index Files . . . . . . . . . 171 15.10.7.7 Exporting a List of the Forum Names . . . . . . 172 15.10.7.8 Rebuilding the Main Control Files . . . . . . . 172 15.10.7.9 Resetting All Privileges . . . . . . . . . . . 172 16. QWK Services . . . . . . . . . . . . . . . . . . . . . . . 173 16.1 Sysop Configuration . . . . . . . . . . . . . . . . . . 173 16.1.1 Service Files . . . . . . . . . . . . . . . . . . . 175 16.2 User Configuration . . . . . . . . . . . . . . . . . . . 175 16.3 Off-line QWK Configuration . . . . . . . . . . . . . . . 177 16.4 QWK Download Operation . . . . . . . . . . . . . . . . . 179 16.5 QWK Menu Actions . . . . . . . . . . . . . . . . . . . . 180 17. TSX-Term . . . . . . . . . . . . . . . . . . . . . . . . . 181 17.1 Why get TSX-Term? . . . . . . . . . . . . . . . . . . . 181 17.1.1 Licensing . . . . . . . . . . . . . . . . . . . . . 181 17.1.2 Background file transfer . . . . . . . . . . . . . . 181 17.1.3 Full ANSI and color support . . . . . . . . . . . . 181 17.1.4 Dialing directory . . . . . . . . . . . . . . . . . 182 17.1.5 Compressed data stream . . . . . . . . . . . . . . . 182 17.1.6 Full integration . . . . . . . . . . . . . . . . . . 182 17.2 How to distribute TSX-Term . . . . . . . . . . . . . . . 182 17.3 How to implement support for TSX-Term . . . . . . . . . 182 17.4 TSX-Term and file transfer . . . . . . . . . . . . . . . 183 18. Usenet Support . . . . . . . . . . . . . . . . . . . . . . 184 18.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 184 18.2 Programs related to usenet . . . . . . . . . . . . . . . 184 18.3 Bag file and rnews message format . . . . . . . . . . . 185 18.4 Receiving Pagesat data with GETSAT . . . . . . . . . . . 187 18.4.1 Introduction . . . . . . . . . . . . . . . . . . . . 187 18.4.2 Input to GETSAT . . . . . . . . . . . . . . . . . . 187 18.4.3 Output of GETSAT . . . . . . . . . . . . . . . . . . 187 18.4.4 The GETSAT event log . . . . . . . . . . . . . . . . 188 18.5 Unzipping compressed Pagesat files . . . . . . . . . . . 188 18.6 Tossing incoming mail with BAGTOSS . . . . . . . . . . . 189 18.7 An example using GETSAT, BAGTOSS, and FSWEEP. . . . . . 189 Contents vii 18.8 Installing UUCICO . . . . . . . . . . . . . . . . . . . 190 18.9 Receiving Usenet mail with UUCICO . . . . . . . . . . . 191 18.10 Sending mail with UUCICO . . . . . . . . . . . . . . . 192 19. Fidonet Support . . . . . . . . . . . . . . . . . . . . . . 193 19.1 Introduction . . . . . . . . . . . . . . . . . . . . . . 193 19.2 Getting Fidonet Going . . . . . . . . . . . . . . . . . 194 19.3 Seting up the fidonet message base . . . . . . . . . . . 194 19.4 Specifying fidonet configuration . . . . . . . . . . . . 195 19.5 The Fidonet Scanner . . . . . . . . . . . . . . . . . . 196 19.5.1 Introduction . . . . . . . . . . . . . . . . . . . . 196 19.5.2 Scheduling the Fidonet Scanner . . . . . . . . . . . 196 19.5.3 How FIDOSCAN works . . . . . . . . . . . . . . . . . 197 19.5.4 Fidoscan command options . . . . . . . . . . . . . . 197 19.6 The Fidonet Tosser . . . . . . . . . . . . . . . . . . . 198 19.6.1 Introduction . . . . . . . . . . . . . . . . . . . . 198 19.6.2 Scheduling the Fidonet Tosser . . . . . . . . . . . 198 19.6.3 Customizing FIDOTOSS.CMD . . . . . . . . . . . . . . 198 19.6.4 The FIDOTOSS command . . . . . . . . . . . . . . . . 199 19.7 Using Frontdoor with TSX-BBS . . . . . . . . . . . . . . 200 20. Scheduled Events . . . . . . . . . . . . . . . . . . . . . 204 20.1 The Schedule Server . . . . . . . . . . . . . . . . . . 204 20.2 The Mail Sweeper . . . . . . . . . . . . . . . . . . . . 205 20.3 The Forum Sweeper . . . . . . . . . . . . . . . . . . . 205 20.4 The Fidonet Tosser . . . . . . . . . . . . . . . . . . . 206 20.5 The Fidonet Scanner . . . . . . . . . . . . . . . . . . 206 20.6 The Bag File Tosser . . . . . . . . . . . . . . . . . . 206 20.7 The Log File Sweeper . . . . . . . . . . . . . . . . . . 207 21. For Further Information . . . . . . . . . . . . . . . . . . 208 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Chapter 1 Introduction TSX-BBS is a full multi-line bulletin board system (BBS) that runs in conjunction with TSX-32 and TSX-Lite. Like TSX, TSX-BBS is available as a commercial product and as a shareware program. Since TSX-BBS is a separate product from TSX and TSX-Lite, it is distributed independently (although you need TSX-32 or TSX-Lite to run TSX-BBS). The following is a summary of some of the major features of TSX-BBS: 1.1 A Multi-Line System Designed from the ground up as a multi-line operating environment, TSX-BBS can support up to 256 lines on a single computer. The reason TSX-BBS can do this is that it was designed specifically to run with TSX and to use the features of the operating system in the most efficient manner possible. So, instead of a room full of computers, you can have a single system running TSX-BBS connected through an intelligent serial multiplexer to many modem lines. For medium to large installations, this could save thousands (or even tens of thousands) of dollars in hardware expenses, not to mention the complexity of maintaining a large networked system. An advantage of a multi-line TSX-BBS system is that it provides a smooth growth path. Many systems run well for one or two lines, but when you grow you will hit a barrier that necessitates a radical change. With TSX-BBS, you can start out with a small system and grow smoothly to an enormous system. 1.2 Super System Capacity Suppose your dreams are so big that you think you will outgrow a single computer no matter how efficient the software is. Relax, TSX-BBS will take care of you. For extremely large configurations, TSX systems can be networked together so that you can grow without bounds. With its TCP/IP networking option, you can link multiple TSX systems together. Any program on any computer in the network can transparently access any file. Because TSX networking uses a peer-to-peer model, you do not have to dedicate a computer as a "file server". All computers in the network can store files and run the TSX-BBS system. 1 Chapter 1. Introduction 2 1.3 Reliable, Non-stop Operation If you are running a single-line hobby board it may be acceptable to take the system down periodically for maintenance and improvements. But, if you are serious about running a professional quality board, you need a BBS system that will run reliably, non-stop, 24-hours a day. TSX-BBS is such a system. All of the BBS maintenance functions such as adding and modifying user authorizations, reviewing and posting new uploads, and backing up files can be done without stopping the BBS or interrupting your users. You can do new program development using the TPL language, C, Pascal, or the language of your choice, while the BBS is in full operation. You can develop and test menu changes without interrupting your users. And, the sysop (or properly authorized users) can do development and maintenance from dial-in connections as well as from the local console. Routine operations such as new user registrations are completely automatic. Internet Usenet newsgroups, Fido echoes, and netmail processing is automatic with messages being posted in real-time as they arrive. TSX-BBS can even be configured to automatically create new Fido and Usenet newsgroups without sysop intervention. You can literally take a vacation without most of your users being aware that your board is unattended. 1.4 A Sysop's Dream With other multi-line BBS systems, the computer is dedicated to running the BBS software and the sysop must use auxiliary computers for tasks such as viewing uploaded GIF files, running "door" programs, and processing incoming satellite feeds. TSX-BBS is the only multi-line BBS system that lets the sysop run DOS programs, view GIF's, do file maintenance, and run games while the BBS is live on the same PC. The same computer that is running TSX-BBS can process incoming satellite data including Usenet feeds and add it to your board in real-time. Since most DOS programs such as WordPerfect, dBase, Foxpro, CSHOW, Procomm, and Windows 3.1 run under TSX with the BBS in operation, you can run your business on the same computer and at the same time that you run your BBS. Using the HOST program that is provided with TSX, or your own favorite communications program, you can call other systems and upload and download files while your BBS is running on the same computer. 1.5 Door Program Support "Door" programs are applications designed to run in cooperation with a BBS to provide extended services such as games. Because traditional multi-line BBS systems dedicate the computer to running the BBS software, they are unable to execute popular door Chapter 1. Introduction 3 applications. TSX-BBS, on the other hand, can execute door programs on the same computer with the BBS. And, many users can run doors at the same time. TSX-BBS takes care of the details of creating a DOOR.SYS "drop" file with user information. TSX includes an internal, optimized "FOSSIL" communication driver for efficient operation of door programs. See Chapter 14 for a full discussion of door program support. 1.6 Flexibility is the Key Successful computer bulletin boards evolve over time. As your system grows and you acquire new users and add more lines, you will develop new ideas for improvements and new features. It is important that you select a BBS package that allows you to customize your system and doesn't box you in with fixed menus and no way of adding extensions. TSX-BBS comes with a complete set of menus and support programs so it is easy to get up and running the same day you receive it, but it doesn't hold you back when you are ready to do your own development and customization. Virtually every menu, phrase, and color can be changed. Some sysops like very flamboyant menus, others prefer more reserved ones; have it your way. With a little creative effort you can configure TSX-BBS to present exactly the image you desire. And, you will find that this customization is surprisingly easy; we give you the tools and materials, you can put them together in many different ways. TSX-BBS comes with an advanced menu compiler that allows you to modify any of the standard menus and create new menus of your own design. You can change the menu tree structure, change the wording of menu options, translate them to foreign languages, add and remove menu items, and integrate text from ANSI and RIP editors. See Chapter 5 for a full discussion of menu design. For the finest level of customization you can change the phrases and colors presented by each "building block" menu action. This is especially useful for creating bulletin boards to serve users who prefer a language other than English. Don't let your users down. You can enhance and upgrade your system while it is running continuously, 24-hours a day. You can create your own test menus while your users continue to run with the production menus. When you are ready, you can add the new menus to the production system without taking the BBS down or even interrupting on-line users. You can even configure TSX-BBS to present experimental menus and features on selected lines or for selected users only. Chapter 1. Introduction 4 1.7 Use TPL to Extend Your System The optional TSX Programming Language (TPL) is the ideal tool for writing extensions to TSX-BBS. You can also use TPL for developing your own application programs. Using TPL, you can develop plug-in enhancements to your BBS that are a seamless part of the system. If you are so inclined, you can use TPL to develop extensions and commercial applications that can be marketed in source or object language form to other TSX-BBS sites. TPL is a powerful programming language with a C-like syntax. TPL includes integer, real, and string variables and constants. The string variables are especially powerful because they have dynamic size so you never have to reserve a fixed size area to hold a value. You can also write string functions that accept and return strings of varying sizes. The TPL language includes over 300 built-in library functions. Many of these functions perform BBS operations such as adding files to the BBS file libraries or getting information about registered BBS users. It is easy to write TPL programs to add new files using the FILE_ID.DIZ descriptions so that you do not have to type multi-line descriptions. You can also write TPL programs to produce reports such as a list of the most frequently downloaded files, or a list of users whose accounts will expire during the next month. A communication "script" facility is integrated into the TPL language. You can write TPL programs that dial other bulletin boards, check for new files, download files, and add them to your BBS file library; this can be done while your BBS is in operation and without intervention on your part. Because the communication script facility is an integral part of the TPL language, all of the other language features are available such as dynamic string variables, functions, file I/O, and X/Y/Z-modem transfers. You can schedule scripts (and other TPL programs) to run at specified times of the day. 1.8 File Libraries A good file library facility is important for most bulletin boards and is the primary reason for existence for many. TSX-BBS provides a world class file library. You can set up any number of file areas and organize them in hierarchical categories (CD-ROMs, IBM files, Macintosh, etc.). File descriptions can be up to 16 lines long and TSX-BBS stores extended information about each file including the date and time when it was uploaded, the name of the person who uploaded the file, the number of times that the file was downloaded, and the date of the last download. Users can download files one at a time or they can tag files while browsing and then download them as a group. Daily download byte and time limits can be set for each user. Chapter 1. Introduction 5 TSX-BBS includes a powerful file search facility. Users can search file names and descriptions for single words or for words joined with the logical operators 'AND' and 'OR'. For example, a valid search expression is "GAMES AND WINDOWS", or "HIV OR AIDS". A date search allows users to find files uploaded since the last time they checked or since a specified date and time. The search can span all file areas or can be restricted to specified areas. The sysop can set up a private upload area for all user uploads so that the files can be examined before being publicly posted. It is easy to set up private file areas for groups of users or companies that may want to use your board as a support center. See Chapter 7, starting on page 71, for additional information about the file library. 1.9 Personal File Workspace In addition to file libraries, the sysop may authorize users to store files in a "personal file workspace". This is a private directory for the user's personal use. It is also possible for several users to share the same workspace. Each user can be disallowed from using a workspace, authorized to use a temporary workspace which is deleted when the user logs off, or allowed to have a permanent workspace. The sysop may place limits on the size of each user's personal file workspace See Chapter 8, starting on page 85, for additional information about personal file workspaces. 1.10 Newsgroups and Discussion Forums TSX-BBS includes a powerful message storage and retrieval system that is ideal for Usenet newsgroups, Fido echoes and other types of discussion forums. The message system can efficiently store and recall messages from thousands of message areas making it ideal for major Usenet storage sites. The maximum number of messages and message areas is limited only by available disk space. Message text compression is performed automatically to reduce disk space requirements. Messages are organized in a hierarchical (tree-structured) fashion. The top level can have categories such as Usenet and Fido. Within the Usenet group there might be subcategories such as "alt" and "comp". Within usenet.alt you would find additional subsub-categories, etc. Users can explore the areas by moving up and down through the hierarchical levels or by browsing the full set of forums as an alphabetical list. By using sophisticated indexing techniques, TSX-BBS is able to provide virtually instantaneous access to any message area. Users can locate message areas by doing searches for words in the area name. Users also can Chapter 1. Introduction 6 search for messages containing specified words and expressions in the body of the message. Within an area, messages are sorted by their creation date. Messages on the same topic are grouped into "threads" making it easy to follow an exchange of messages. TSX-BBS keeps track of the last message read in each area so that users can easily read new messages in forums with many messages. Reading messages in one area does not affect the last-message-read pointer for other areas. A "privilege expression" can be associated with each area to control which users can access the area. This makes it easy to set up adult discussion forums and to create private forums for groups that are using the board as a message exchange system. Forum access restrictions are especially useful for Usenet which has a number of newsgroups which are not suitable for general distribution. A QWK facility is built into TSX-BBS to provide efficient downloading of messages for off-line readers. There are "tosser" programs available to process incoming Fido and Usenet messages. At the option of the sysop, new message areas (categories) can be created automatically by the tosser when messages arrive for areas that did not previously exist. The sysop can block all automatic area creation or can enable it only for subcategories of selected areas. See Chapter 9, starting on page 89, for additional information about discussion forums. 1.11 E-mail TSX-BBS includes a powerful electronic mail (e-mail) system that allows users to send messages to each other. They can also send and receive SMTP (Simple Mail Transfer Protocol) messages through the Internet and they can send and receive Fido netmail messages. 1.12 Direct Internet Access In addition to Internet mail and Usenet newsgroups, TSX-BBS offers direct, interactive access to the Internet using FTP and Telnet. The File Transfer Protocol (FTP) program allows you to browse through files on other computers connected to the Internet. Once you have found a file of interest, FTP transfers the file to a "personal file workspace" directory on the TSX-BBS system. You can then use X/Y/Z-Modem to download the file from the TSX-BBS work area to the local computer. Telnet is a terminal emulator program that you can use to log onto another computer connected to Internet. With Telnet you can be an interactive user on computers around the world. Chapter 1. Introduction 7 If you authorize it, users can also access your BBS through the Internet by using Telnet. They run Telnet on their personal computers and specify your BBS address as the host address. They then log on just like dial-in users and have full access to the BBS. FTP and Telnet run as "native" programs on the same computer that is running TSX-BBS. There is no need to buy a separate, dedicated Internet server computer. You can provide your users with full Internet access and do it all with a single computer system. See Chapter 12, starting on page 120, for additional information about Internet access. 1.13 Incoming SLIP connections If you have an Internet connection, you can resell Internet connections to your users. Your users can call your BBS, log on, and then shift their connection from ASCII to SLIP (Serial Line Interconnect Protocol). They are then connected to the Internet through your BBS and they can run programs such as FTP, Telnet, and Mosaic on their local computers to access sites on the Internet. You can limit which users are authorized for SLIP access and the BBS daily time limits apply to SLIP connections. 1.14 On-line "Chat" A popular multi-line BBS feature is real-time conferencing, "Chat". Chat allows users to set up round-table conferences where they can carry on multi-party discussions in real-time. TSX-BBS chat allows the sysop to create permanent discussion topics; users can create temporary chat areas that are deleted automatically when the last user leaves the area. The chat system features split screen mode which allows users to view the ongoing conversation while composing their own contributions. See Chapter 13, starting on page 127, for additional information about the chat system. 1.15 TSX-BBS System Security TSX-BBS allows the sysop to set many privilege and limit values for each user. Controls such as daily time limit, download file limit, and use of individual system functions such as the file library, E-mail, chat, QWK, etc. may be set for each individual user. To simplify management, the sysop may also define user "classes" which describe sets of limits and privileges. A class can then be assigned to a user, changing each of the users limits and privileges to those of the class. The TSX-BBS user privilege system is simple but extremely powerful. Each user is assigned a "security level" that ranges from 0 to Chapter 1. Introduction 8 65535. In addition, there are 80 sysop-defined privilege flags that may be turned on or off. The meaning for each privilege flag may be assigned by the sysop. The privilege flags can be used in privilege expressions along with the security level and other conditional tests such as the date, time, day of the week, etc. TSX-BBS privilege expressions can include multiple logical items with 'AND' and 'OR' logical operators and parentheses for grouping. For example, the following privilege expression is true for a user who has a security level equal to or greater than 50 or has privilege flag 1 enabled: "(PRIVLEV>=50||P1)". The following privilege expression is true only on Saturday: "(DAYOFWEEK==7)". See Chapter 4 for a full discussion of privilege expressions. In addition to the security level and privilege flags, the sysop can also assign a "group" number to users. This can be used to set up private file and message areas accessible only to members of the group. This is extremely useful for commercial BBS operations that provide support areas for various companies or organizations. See Chapter 4, starting on page 31, for additional information about security control. 1.16 System Control TSX-BBS comes with a "SYSOP" program that provides comprehensive control over your system. With the "dashboard" display you can monitor which lines are in use, what users are on-line, and what activities are taking place. The sysop can also "spy" on user sessions. Real-time statistics displayed include the number of logons, new user authorizations, files uploaded and downloaded, messages sent and received, door programs executed, and overall system loading. See Chapter 15 for a full discussion of the SYSOP program. The sysop can examine and modify user authorization entries, change privileges and examine usage statistics while the system is running. Statistics kept for each user include the date of the user's first and last logons, the total connect time, bytes uploaded and downloaded, and information about the current day's usage. Log files can be enabled to record even more detail including the date and time of each file upload and download. The sysop can examine and edit file descriptions and monitor file download counts. A cut-and-paste clipboard makes it easy to move files from one file area to another. All of this can be done while the system is in full operation. Chapter 2 Installing TSX-BBS 2.1 Demonstration, Shareware Version of TSX-BBS TSX-BBS is a commercial product developed and supported by S&H Computer Systems, Inc. However, there is a demonstration, shareware version of TSX-BBS that may be freely copied, passed around, and posted on bulletin boards. The shareware version is intended for demonstration purposes only. The shareware version is limited in that it provides only the basic BBS operations such as file libraries, discussion forums, e-mail, etc. It does not provide any of the optional components such as Internet connectivity, Fido, and chat. The TPL programming language is also not available with the shareware version. The shareware version of TSX-BBS prints a message when each user logs on notifying the user that the TSX-BBS system is an unregistered, demonstration version. The shareware version of TSX-BBS is intended to be used with TSX-Lite, the shareware version of the TSX-32 operating system. If you have obtained a shareware copy of TSX-BBS you must also find and install a copy of TSX-Lite. The current version of TSX-BBS requires TSX-Lite version 4.20 or later. The TSX-Lite files are named TSX420A.ZIP, TSX420B.ZIP, TSX420C.ZIP and TSX420D.ZIP. The demonstration version of TSX-BBS can also be used with a TSX-32 system. Note: the latest copies of the shareware versions of TSX-BBS and TSX-Lite can always be obtained from the S&H Support BBS: 615-320-1820. You can also download the complete TSX-BBS reference manual and the TPL programming language manual as well as example programs and shareware add-ons. 2.2 TSX-32 System Generation Considerations The first step in installing a TSX-BBS system is to install the underlying TSX-32 or TSX-Lite operating system. With TSX-Lite you are restricted to running a maximum of two simultaneous users. With TSX-32 you are limited only by licensing and performance considerations. To install TSX-32, you should follow the instructions in the TSX-32 Installation and System Generation Manual. The procedure for installing TSX-Lite is described in the documentation that comes 9 Chapter 2. Installing TSX-BBS 10 with it. Since the installation procedure is thoroughly described there it will not be repeated here. There are a few TSX system generation parameters that must be set appropriately to enable optimal performance of TSX-BBS. They are described in the following sections. 2.2.1 General System Parameters The TSX system generation parameters described in this section affect overall operation. To set them you should run the TSGEN program under TSX by changing to the TSX system directory (\tsx32sys) and issuing the following command: TSGEN If your system generation configuration file has the default name, TSX32.GEN, press Enter when asked for the name of the GEN file. You will then be presented with a menu from which you should select the "Set Tuning Parameters" option by typing 'S'. You should then be presented with a menu whose top item is "All parameters". Press Enter to select this item. You will now be presented with a long list of system generation parameters. You may press the arrow keys and Page-up/Page-down to scroll through the list. You may also type a letter to reposition the display to the first parameter beginning with the letter you type. To change an item, position to it and press Enter. Press ESC to return to this menu after you have set the parameter. Set each of the following system generation parameters: DOBBS -- Set to 1. This parameter tells TSX that TSX-BBS will be running and causes the start-up system initialization job to execute a batch file named "SY:STARTBBS.CMD" which initiates detached jobs needed by the execution of the BBS. DOTSXTERM -- Set to 1 if any of your users will be using the TSX-Term communications program to connect to TSX-BBS. Setting this parameter to 0 disables TSX-Term support and saves about 40k bytes of space in the kernel. See Chapter 17 for additional information about TSX-Term. NEWTEMPFILES -- Set to 1. This allows creation of new files with the same names as existing file that are currently open. The superseded files are replaced when they are closed. ZMODEM -- Set to 1. This enables support for X-, Y-, and Z-modem protocols. 2.2.2 Serial Line Parameters Once you finish changing the general system parameters, press ESC repeatedly until you return to the first TSGEN menu that gives you the choices "Set Tuning Parameters" and "Manage equipment List". Press 'M' to select "Manage Equipment List". You will then be Chapter 2. Installing TSX-BBS 11 presented with a list of each device known by TSX. The device names on this menu have a two letter device type code (for example, "TT" for terminal lines, and "DH" for fixed disks) and a controller letter. Device name "TTA" is normally the console terminal, "TTB" is COM port 1, and "TTC" is COM port 2. If you have genned in a serial multiplexer it will have a name of the form "TTx" where 'x' is the controller letter you specified. You should use the arrow keys to highlight the entry for the serial device whose lines you wish to set and then type 'U' to select the unit control menu. This menu will display a list of the serial lines attached to the hardware controller. There will be one entry in the case of COM ports and more than one entry in the case of serial multiplexers. To change the parameters for an individual unit, use the arrow keys to highlight the selected unit and type 'U' to select "Unit settings". You will then be presented with the first of set of screens with parameters that can be set for the unit. Use the arrow keys and Page-up/Page-down keys to position to entries to be changed. You should set the following parameters: SPEED -- Press Enter and a list of available baud rates is displayed. Highlight the speed you desire and press Enter to select it. If you are using a "smart" modem that has a fixed rate of communication to the computer, you should set that rate as the default speed. If you are using 14.4k baud modems the recommended line speed is 19.2k. If you are using 28.8k baud modems the recommended line speed is 38.4k baud. TERMTYPE -- Press Enter and you will be presented with a list of terminal types. Highlight the desired terminal type and press Enter to select it. Here is a summary of some of the terminal types: ANSI -- Terminals or terminal emulator programs that handle the basic ANSI control sequences. This is the best choice if the system is being accessed using a terminal emulator program such as Procomm or Telix. This is the default TSX-Lite terminal type. This is the recommended terminal type for TSX-BBS lines. VT100 -- Digital Equipment Corporation (DEC) VT-100 terminal. Many terminal emulator programs provide VT-100 as an option. If you select this terminal type and "trash" characters appear on the screen after typing the CLS command or after a session window switch, you should select ANSI terminal type. PCTERM -- Serial PC-Term Terminals. These are serial terminals that have IBM compatible keyboards and transmit make/break keyboard codes like the console keyboard. They can display 25 lines and support the IBM display character set. TSXTERM -- Terminal Emulator. The TSXTERM terminal emulator program, which is provided with TSX, can be run on a remote computer that is connected to your TSX-Lite system via Chapter 2. Installing TSX-BBS 12 either a hardwired serial connection or a modem. This is the best type of TSX workstation. See Chapter 17, starting on page 181, for additional information about TSXTERM. PARITY -- The standard setting for TSX is 8-bits, no parity. Press Enter and you will be presented with a choice of even, odd, or no parity. PHONE -- Set this entry to 'Y' for lines connected to modems. AUTOBAUD -- set this parameter to 'N'. START -- Set this item to 'Y' to cause the line to start automatically when a connection is established. SYSPASSWORD -- If you set this field to 'Y' users will be prompted with the string specified by the SYSPASSPR sysgen parameter (default is '!') and they must enter a password string that matches that specified by the SYSPASSWORD sysgen parameter. The recommended setting is 'N' unless you need the additional system security. LOGON -- If this unit is being used only as an I/O device (e.g., serial mouse, modem for dial-out calls, etc.) set this field to 'N' to prevent users from logging onto the line. Set this parameter to 'Y' for normal dial-in type lines. CMDFILE -- You may specify the device, directory, and name of a command file to be executed each time this line logs on. The default start-up command file is SY:START.CMD. You should specify SY:BBS.CMD for lines that are to start the TSX-BBS system automatically when a connection is established. HANDSHAKING -- Select RTSCTS for the standard hardware handshaking used by most modern high-speed modems. Select XONXON if XON (control-Q, DC1) and XOFF (control-S, DC3) characters are used for software flow control. If you are using a 14.4k or 28.8k modem you will almost certainly want to select RTSCTS handshaking. BOARDHS -- Set to 'Y' to enable hardware controller handshaking mode for high-speed modems. ORINGSIZE -- Set to 3600 (or larger) for BBS lines. FIXEDSPEED -- Setting this option to 'Y' causes TSX to lock the speed of the line to the speed set during system generation. If the option is set to 'N' then programs can change the line speed. MRESET -- You may specify a modem reset string to be sent to the line whenever a user logs off or a program releases control of the line. To enter control characters in the string specify the caret character ('^') in front of the letter. For example, "^M" means control-M which is carriage return. Chapter 2. Installing TSX-BBS 13 Press ESC to exit from the unit parameter screens after you change the desired settings. Press ESC three more times to exit from TSGEN. The parameter settings are written to the TSX32.SYS kernel file and are recorded in the TSX32.GEN system generation parameter file. You must reboot your computer and restart TSX to make them take effect. 2.3 Modem Setup Note: In discussing modems, several terms come up frequently that you should understand. The term "DTE" (Data Terminal Equipment) refers to a computer (or a serial terminal). The term "DCE" (Data Communications Equipment) refers to a modem. Modems are controlled using a set of commands that begin with the sequence "AT". For example, "ATDT" begins touch-tone dialing. The "basic" commands such as ATDT, ATH, ATQ, and ATE seem to be standard across all brands of modern modems. Advanced commands usually begin with "AT&" or "AT%". These commands are not standardized across all brands of modems. In this manual we will give examples based on the Hayes command set, you should refer to your modem manual for the equivalent command. The TSX serial port that a modem is connected to should be set to a baud rate higher than the actual communications rate. You should do this using TSGEN as described in Section 2.2.2. If you are using a 14400 baud modem, the serial port rate should be set to 19200; for 28800 baud modems, the serial port rate should be set to 38400. Once the TSX port speed has been correctly set you should use the TSX "HOST" command to cross-connect to the serial line. For example, to connect to a modem on COM port 1, which corresponds to the TSX device name TTB0:, use the command: HOST TTB0: Make sure your modem is in echo mode by typing the command "ATQ0E1" which should cause the modem to echo "OK". You can now type commands to the modem. Note: to exit the HOST connection type control-backslash followed by 'X'. Modems should be configured to communicate with the TSX-BBS system at a fixed baud rate. For most modems this is done by sending them the command "&B1" (this would be typed "AT&B1" because all modem commands begin with "AT"). Note: In a computer-to-computer connection there are actually three baud rates involved: 1. The speed between the TSX-BBS computer and its modem. 2. The "link" speed between the two modems. 3. The speed between the modem and the user's computer. Chapter 2. Installing TSX-BBS 14 Computer Modem Modem Computer (DTE) <---> (DCE) <-------> (DCE) <---> (DTE) TSX-BBS works best if you can configure your modem to report the link speed (the speed between the two modems). Next, the modem should be set to perform hardware flow control. This causes the modem and TSX to use the Request to Send (RTS) and Clear to Send (CTS) control signals to coordinate flow control. If you modem uses Hayes compatible commands, the mode command to do this is "&H1". The modem should also be set to return verbal result codes. In this mode the modem will send a string to TSX such as "CONNECT 14400" when a connection is made. If your modem uses a Hayes compatible command set, this can be done using the modem command "&A3". If you have a choice, set your modem to report the link connection rate (i.e., the speed that the two modems are talking to each other) rather than the speed with which the modem is talking to TSX. The modem should be set to report the "true state" of the Carrier Detect (CD) signal. Carrier detect is asserted when the modem is receiving a good signal from another modem. Some modems set this with a DIP switch, others use the command "&C1". For proper modem control by TSX-BBS, it is essential that your modem report whether the carrier detect signal is actually being received rather than always reporting that carrier is detected which is the default case for some modems. The modem should be set to hang up when the Data Terminal Ready (DTR) signal is dropped. Most commonly, the command to do this is "&D2". Once you have issued these commands to the modem, you should save the settings in nonvolatile random access memory (NVRAM) by issuing the modem command "&W". Note: in addition to making the settings permanent, the "&W" command also causes the modem to use the baud rate in effect when the command was issued each time it receives an incoming call. Note: some modems use an S-register to determine the communication speed for incoming calls. You can exit from the HOST command by typing control-backslash followed by 'X'. Chapter 2. Installing TSX-BBS 15 2.4 TSX-BBS Installation 2.4.1 Installing a Commercial System If you purchased a TSX-BBS system you will have received a diskette labeled "TSX-BBS". To install TSX-BBS first boot to DOS, then insert the diskette in your 'A' or 'B' drive and type: x:INSTALL where 'x' is 'A' or 'B' depending on the drive you are using. The installation procedure will ask you to provide the name of the directory where the TSX-BBS files should be installed; the default name is "C:\TSXBBS\". Two subdirectories are created under this directory. Their names are "BIN" and "DATA". The BIN subdirectory contains the executable programs for TSX-BBS and other system files. The DATA subdirectory contains site-dependent data files and log files. After you enter the requested information, the TSX-BBS installation procedure will decompress the files on the diskette and create the directories. Once the installation procedure is completed you must run MINIGEN to regenerate TSX and then you must start TSX before you can run the BBS. 2.4.2 Installing the Demonstration System The shareware, demonstration version of TSX-BBS is distributed as a ZIP archive with the name TSXBBSnn.ZIP where nn is the version number. To install the demonstration version, boot to DOS and create a temporary directory and select that directory as your current directory; then decompress the ZIP file into the temporary directory. Next, type INSTALL to execute the BAT file in the temporary directory. The installation procedure will ask you to provide the name of the directory where the TSX-BBS files should be installed; the default name is "C:\TSXBBS\". Two subdirectories are created under this directory. Their names are "BIN" and "DATA". The BIN subdirectory contains the executable programs for TSX-BBS and other system files. The DATA subdirectory contains site-dependent data files and log files. After you enter the requested information, the TSX-BBS installation procedure will decompress the files on the diskette and create the directories. Once the installation procedure is completed you must run MINIGEN to regenerate TSX and then you must start TSX before you can run the BBS. Chapter 2. Installing TSX-BBS 16 2.5 TSX-BBS Initialization After installing TSX-BBS and making the necessary changes to the TSX operating system, you must start TSX before you can run TSX-BBS because TSX-BBS can run only under TSX, not DOS. Once TSX is running you are ready to start the TSX-BBS SYSOP program to perform some BBS initialization. The SYSOP program is fully documented in Chapter 15. This section is intended to provide the minimum information needed to get you started. TSX-BBS needs two file directories which are created during the installation process: one stores the executable programs, menus, language phrase file, and other system files. The second directory holds site-dependent files such as your configuration information, file library descriptions, and log files created by various BBS utility programs. TSX-32 allows the use of "logical device names" to assign a physical device and directory to a logical name. Unlike DOS, TSX-32 logical device names can be more than one character long. TSX-BBS assigns the logical name "BBSBIN:" to the BBS system file directory and "BBS:" to the site-dependent data file directory. The default directory names are "C:\TSXBBS\BIN\" and "C:\TSXBBS\DATA" but you may select different names if you wish. The installation procedure creates a TSX-32 command procedure (like a DOS batch file) named BBSASN.CMD in the TSX-32 system directory (\TSX32SYS) which contains ASSIGN commands for the BBS and BBSBIN logical names. If for some reason you need to change the BBS directories, you could edit this file. Start the SYSOP program by typing the command: SYSOP 2.5.1 General Setup From the main menu type 'G' to select "General Setup". Enter the following items of information: BBS name -- The name of your BBS as you want it displayed to your users. Location -- The location of your BBS. Phone number -- The primary dial-in phone number of your BBS. QWK ID -- This string is used to name packets downloaded and uploaded during QWK message transfers. Normally it should have a name related to your BBS name. Sysop name -- The name of the primary sysop should be entered for "Sysop 1 name". If there are co-sysops, their names may be entered for "Sysop 2 name" and "Sysop 3 name". Chapter 2. Installing TSX-BBS 17 Inactivity limit -- If a user remains inactive for this number of minutes, he or she will be logged off. You may specify 0 for this parameter if you do not want to impose an inactivity time limit. Callback verification -- Specify 'Y' if you want the BBS to call new users to verify that they have entered correct phone numbers. See Section 6.2 on page 63 for additional information about the callback procedure. Date format -- You may select three different formats for printing dates: 0 = mm/dd/yy 1 = dd/mm/yy 2 = yy.mm.dd Temp directory -- This is the name of the device and directory where the BBS will create temporary files for users. A subdirectory for each BBS line is created under the BBS root directory that you specify. Time zone -- Specify your time zone name. For example, "CST" would be specified for Central Standard Time. Once you fill in the General Setup screen, press ESC to return to the main menu. 2.5.2 User Authorization The next thing that you should do is authorize yourself to access the BBS. From the main SYSOP menu type 'U' to select "User Authorization". The next screen will be a list of authorized users; initially this list will be empty. The 'U' to select "User classes". A "class" is a set of privileges and limits that can be used to "stamp" a user entry. Initially, there should be classes defined for "BASIC", "VERIFIED", "EXPIRED", and "SYSOP". See Section 15.2.4 starting on page 145 for additional information about classes. Some classes have specific uses as described in Chapter 6. You can define your own classes and change the limits and privileges associated with the default classes. To examine the limits and privileges associated with a class, use the arrow keys to select a class and press Enter. You should examine the default classes and make any changes that you wish. Once you have finished examining and modifying classes, press ESC to return to the "Users" list. Next, type 'A' to select "Add user". Create an entry for yourself using the arrow keys to move between fields and the page-up/page-down keys to move between the pages of the entry. You Chapter 2. Installing TSX-BBS 18 can press F1 to get help about the field you are currently positioned to. You can leave the limit and privilege entries blank at this time. When you are finished creating your entry, press ESC to return to the "Users" list. Now, use the arrow keys to highlight the entry you have created and press 'C' to select "Class". A pull down menu will appear with a list of all defined classes. Use the arrow key to select the "SYSOP" entry and press Enter. This will assign the privileges and limits associated with the selected class (SYSOP) to the selected user. If you wish, you can examine the user entry to see the values that have been assigned. See Section 15.2 starting on page 142 for additional information about authorizing users. 2.5.3 Scheduled Utilities From the main SYSOP menu type 'S' to select "Schedule Utilities". The first time you enter the "Schedule Utilities" menu the SYSOP program creates a control file with a list of the default utility programs. You will see a list of the scheduled utilities. To examine information about a utility program, use the arrow keys to highlight an entry in the list and press Enter. The first screen displays general information about the utility program. Press Page-down to advance to the screens that list the times of the day when the utility program will be run. See Chapter 20 for additional information about scheduled utility programs. 2.5.4 File Library Setup Assuming you want to have a file library, you will need to use the SYSOP program to set up some file sets. Extensive information about the file library is presented in Chapter 7; this section will take you through the process of creating an example file set. From the SYSOP main menu type 'F' to select "File library". The screen displayed will be a list of defined file areas; initially this list will be blank. Type 'F' to select "File set create". A "file set" is a collection of files corresponding to a single DOS directory. Typically, files of a similar nature such as games, utilities, swimsuit GIFs, etc. are grouped into a file set. Specify a title for the file set as you want it presented to your users. For example, you might specify something like "DOS Utilities", or "Windows games". The "FDL file" is the name of the file that contains the descriptions of files for this file set. Specify a name of the form "BBS:name.FDL" where "name" is a valid 1 to 8 character file name. The "Directory" entry is the name of the device and DOS directory where files for this file set will be stored. This is the location Chapter 2. Installing TSX-BBS 19 of the actual files that comprise the file set. Specify a full DOS-style directory specification such as "C:\BBS\GAMES\". The "Access", "Download", and "Upload" fields are used for privilege expressions that control which users can access the file area. See Chapter 4 for a full description of privilege expressions. If you leave the "Access" and "Download" fields blank then any user can download from the file set. If you specify "NO" for the "Upload" field then users will be disallowed from uploading to the file set. The "Area#" field controls the order in which the file sets are displayed to the user. If you leave this field blank the file set is added to the end of the list. The "Free download" field controls whether downloads from this file set count against the user's time and byte limits. Specify 'Y' if you want users to be able to download without limits. The "Copy on download" field should be set to 'Y' for CD ROM file sets. It causes TSX-BBS to copy the file to a temporary directory before starting the download. Set this field to 'N' for file sets stored on normal hard disks. The "CD ROM media" field should be set to 'Y' if, and only if, the file set is stored on a CD ROM drive. After you have fill in the screen, press ESC to return to the list of file areas. The area you defined should now be in the list. Repeat this process for any other file sets you wish to define. 2.5.4.1 File Upload Area You should create at least one file set into which users can upload files. When defining this file set, it is recommended that you specify "BBS:UPLOADS.FDL" for the "FDL file" name because this name is used in the standard FILE.MNU file menu that is distributed. If you want this file area to be accessible only to the sysop, specify "P14" for the "Access" and "Download" privilege expressions. Specify "YES" for the "Upload" privilege so that all users can upload to this area. If you examine the FILE.MNU file menu that is provided with your TSX-BBS distribution, you will see that, by default, the 'U' (upload) action is defined as follows: $item key=U action=felupload(bbs:master,bbs:uploads) which causes uploads to go to the file set described by BBS:UPLOADS.FDL. Chapter 2. Installing TSX-BBS 20 2.5.5 Discussion Forum Initialization Fido and Usenet discussion forums are created and initialized automatically by the appropriate "tosser" programs so you do not need to worry about them now. If you want to set up a classified ad forum you should read Section 9.10 starting on page 109. 2.5.6 Local Logon Once you have completed the BBS setup, and have authorized yourself with sysop privilege, you can do a local logon by typing "BBS". This invokes the BBS.CMD procedure in the TSX system directory. You can then log on and experiment with the BBS. To avoid having to type in your name each time you want to do a local logon, edit the file "BBSBIN:SYSBBS.CMD" and replace "first_name" and "last_name" with your first and last names. You can then do a local logon by typing SYSBBS without having to enter your name to logon. 2.5.7 Menu Customization TSX-BBS comes with a set of menu files so that you can get up and running without having to learn how to create TSX-BBS menus. However, eventually you will probably want to custom tailor the menus to your needs. Chapter 5 describes how to create and modify menus. Section 15.4 on page 151 describes how to change menu colors. The main menu is in a file named BBS.MNU which is stored in the BBS system directory. You may want to study it. You will note that it uses the "action=menu(name)" command to invoke submenus. You can determine the names of the various submenus by examining these commands in BBS.MNU. As you modify the menu files it is best if you move your modified copies over to the site-specific data directory so that your menu files will not be overwritten when you install a new version of TSX-BBS. When you do this you must modify the higher-level menus and change the commands to the form "action=menu(BBS:name)" to tell the BBS system to look in the "BBS:" directory rather than in the "BBSBIN:" directory. If you want to move the main BBS menu (BBS.MNU) to a different directory, you must modify the BBS.TPL and LOGON.TPL programs to specify the name of the main menu. Chapter 3 Color and Substitution Operators 3.1 Color operators A color operator may be inserted in menu entries and in other display text to cause TSX-BBS to insert the ANSI escape sequence to select a particular color for the text that follows. If the current user does not have ANSI support enabled, or has selected no-color mode, the color operator is ignored. The form of a color operator is "@Xbf" where 'b' is a hexadecimal digit that selects the background color and 'f' is a hexadecimal digit that selects the foreground (character) color. The 'X' character that follows the '@' character may be written in either upper or lower case. The hexadecimal color values are in the range 0 to 9 or A to F; letters may be written in upper or lower case. You must always specify both the foreground and background color letters so that the entire operator string is exactly 4 characters long. Note that there is no '@' character at the end of the operator. The following is a list of valid background color codes: * BACKGROUND COLOR CODES * Value Attribute Color ----- --------- ------- 0 Normal Black 1 Normal Blue 2 Normal Green 3 Normal Cyan 4 Normal Red 5 Normal Magenta 6 Normal Brown 7 Normal White 8 Blinking Black 9 Blinking Blue A Blinking Green B Blinking Cyan C Blinking Red D Blinking Magenta E Blinking Yellow F Blinking White The following is a list of the valid foreground color codes: 21 Chapter 3. Color and Substitution Operators 22 * FOREGROUND COLOR CODES * Value Attribute Color ----- --------- ------- 0 Normal Black 1 Normal Blue 2 Normal Green 3 Normal Cyan 4 Normal Red 5 Normal Magenta 6 Normal Brown 7 Normal White 8 Bright Black 9 Bright Blue A Bright Green B Bright Cyan C Bright Red D Bright Magenta E Bright Yellow F Bright White For example, the following line shows how the operators might be used to set the colors of various words: @X01Blue on black @XCFBlinking white on red. In addition to using the "@Xbf" color operator you may also select colors by using a substitution operator of the form "@color(name)@" where name is a name that identifies the type of color wanted. When using this method you do not select a specific color like blue on white, rather you select a type of color that can be controlled by the SYSOP program. For example, if you specify @color(heading)@ the following text will be displayed with the color that the sysop has selected for headings. Similarly, @color(base)@ selects the base color. The following is a list of the color type names: Chapter 3. Color and Substitution Operators 23 Name Color Type ---------- ------------------------------------------- BASE Base color BRBRKT Browse list brackets BRNUMBER Browse list numbers BRTAG Browse list tag marker BRTEXT Text in browse lists CHATLABELS Chat: labels for full screen CHATPEOPLE Chat: input from people CHATSERVER Chat: messages from server EDSELECT Editor: text selected for copying FLDATE File dates in file lists FLNAME File names in file lists FLSIZE File sizes in lists HEADING Header color HOTKEY Hot keys HOTBRKT Brackets around hot characters INFO Information items (such as extra file info) MENUBOX Color for menu title box lines MENUTITLE Color for text for menu title PRESSKEY Press any key to continue UINPUT User input Chapter 3. Color and Substitution Operators 24 3.2 Substitution operators You may use "substitution operators" in menu entries and in other display text to cause TSX-BBS to insert certain items of information. A substitution operator has the form "@word@" where 'word' is a word that denotes what item of information is to be substituted. For example, the @date@ substitution operator causes the current date to be inserted in the form "mm/dd/yy" and @first@ causes the user's first name to be inserted. So, for example the line Hello @first@. Today's date is @date@. might be expanded to produce the line Hello Phil. Today's date is 06/08/94. A few of the substitution operators accept argument values enclosed in parentheses. For example the operator @pos(line,column)@ generates the ANSI escape sequence to position the cursor to the indicated location. If there is more than one argument, separate them with commas. If the argument is a string, you may enclose it in quote marks. You must use quote marks if the string contains a close parenthesis or comma character. The following is a list of the valid substitution operators. @baudrate@ -- Inserts the baudrate that the current user is connected at. The value inserted is the actual data communications speed between the BBS and the caller's modem such as 14400, 2400, etc. This value is determined by examining the "CONNECT nnnnn" message returned by your modem when the connection is established. If your modem does not send in a connection speed message, then the value returned is the speed of the line between your computer's COM port and the modem rather than the modem-to-modem speed. @bbs@ -- Name of the bulletin board. @beep@ -- Causes the bell to be rung. @class@ -- Substitutes the user's privilege class name. @clreol@ -- Generates the ANSI escape sequence to clear the remainder of the line. Ignored if the user does not have ANSI capabilities. @cls@ -- Generates the ANSI escape sequence to clear the screen. Generates three line feeds the user does not have ANSI capabilities. @color(name)@ -- Select a color type. See page 22 for additional information about this operator. Chapter 3. Color and Substitution Operators 25 @date@ -- Inserts the current date in the form mm/dd/yy. @dateformat(format)@ -- Inserts the current date and/or time in a format that you specify. The 'format' argument is a string that determines in which form the date-time value is to be inserted. The following formatting codes may be specified: %a -- Abbreviated weekday name. %A -- Full weekday name. %b -- Abbreviated month name. %B -- Full month name. %c -- mmm dd hh:mm:ss yyyy. %d -- Day of the month. %e -- mm/dd/yy. %E -- mm/dd/yy hh:mm. %f -- mm/dd/yy dd/mm/yy yy.mm.dd %F -- mm/dd/yy hh:mm or dd/mm/yy hh:mm %H -- Hour of the 24 hour day. %h -- hh:mm. %I -- Hour of the 12 hour day. %j -- Julian day number. %m -- Month of the year. %M -- Minutes after the hour. %p -- AM/PM indicator. %Q -- mm-dd-yyyy hh:mm:ss. %S -- Seconds after the minute. %t -- Thousands of a second. %w -- Weekday number, 1 for Sunday. %x -- mmm d, yyyy. %X -- hh:mm:ss. %y -- Year of the century. Chapter 3. Color and Substitution Operators 26 %Y -- The year. %z -- dd-mmm-yyyy. %Z -- dd-mmm-yyyy hh:mm. %% -- Literal percent sign. For example, @dateformat(%h)@ inserts the time in the format hh/mm. The "%f" and "%F" formatting operators are somewhat special. They generate a date string of the form "mm/dd/yy" (U.S.A. style) or "dd/mm/yy" or "yy.mm.dd" (European style) depending on which format the sysop has chosen. @delay(time)@ -- Delay execution for the specified number of tenths of a second. @dlavail@ -- Number of K bytes of download available. @dldaylimit@ -- The user's daily K byte download limit. @dnloadcnt@ -- Total number of files downloaded by user. @dnloadsize@ -- Total size of all files that user has downloaded. @dtespeed@ -- Inserts the baud rate value for the connection between your COM port and your modem. This may be different than the actual modem-to-modem baud rate that is inserted by @baudrate@. For example, most sysops set the COM port speed to 19200 when using 14400 baud modems. If a user connects using a 14400 baud modem @baudrate@ will insert 14400 but @dtespeed@ will insert 19200. @eol@ -- Ignore remainder of line including the carriage-return and line-feed characters at the end. This is most commonly used with the @if()@ operator to skip the remainder of the line so that a blank line will not appear in the display. For example, the sequence @if(p1)@@eol@ Displayed only if p1 is true. @endif@@eol@ This line is always displayed. checks the value of p1. If it is true the @eol@ operator is encountered and the remainder of the current line is skipped including the carriage-return and line-feed so nothing is printed for the line at all. If the @if@ is false, the remainder of the line (including the @eol@ operator) is skipped. Similarly, when the line with @endif@ is encountered, the @eol@ operator causes the remainder of the line to be skipped so nothing is printed. Chapter 3. Color and Substitution Operators 27 @expdate@ -- Inserts the expiration date for the account in the format mm/dd/yy. If the account does not have an expiration date, the word "never" is inserted. @first@ -- Inserts the user's first name. @fmpname@ -- Inserts the current default file transfer protocol name such as X-modem, Y-modem, or Z-modem. @forumname@ -- Inserts the name of the discussion forum that the user is currently in. @giget(index)@ -- Inserts the value of a global integer variable. The index argument selects which global integer value to insert; it must be in the range 0 to 99. @grget(index)@ -- Inserts the value of a global real variable. The index argument selects which global value to insert; it must be in the range 0 to 99. @group@ -- Inserts the group number for the user. The group number can be assigned using the SYSOP program. It is intended to identify the user with a company or other organization. @gsget(index)@ -- Inserts the value of a global string variable. The index argument selects which global value to insert; it must be in the range 0 to 99. @handle@ -- Inserts the user's handle name. If the user does not have a handle, "none" is inserted. @last@ -- Inserts the user's last name. @lastcall@ -- Inserts the date and time of the last (previous) call by the current user. @lpp@ -- Inserts the number of lines that are available on the user's screen. @menutitle(title)@ -- Inserts the title string in a box. The number of spaces on the line before the @menutitle@ operator determines how many spaces are placed to the left of the box. This operator should occur on a line by itself. @msgnotify@ -- Inserts the word "Yes" if the user wishes to receive notification messages when a message addressed to the user is posted on a discussion forum. @opibmchar@ -- Inserts the word "Yes" if the user can display IBM graphic characters or "No" if he cannot. @node@ -- Inserts the line index number. Each TSX line that is generated into your TSX system is assigned an index number. The first line (typically the console) is number 1, the second Chapter 3. Color and Substitution Operators 28 is number 2, etc. The @node@ operator inserts the index number of the line that the user is running from. @opansi@ -- Inserts the word "Yes" if ANSI support is enabled for the user or "No" if ANSI support is not enabled. @opansiedit@ -- Inserts the word "Yes" if the full screen ANSI message editor is to be used or "No" if not. @opcolor@ -- Inserts the word "Yes" if color support is enabled for the user or "No" if color support is not enabled. @opibmchar@ -- Inserts the word "Yes" if the user can display IBM graphic characters or "No" if he cannot. @pause@ -- Displays the message "-press a key to continue-" and waits for the user to press a key. @phrase(index)@ -- Inserts the phrase from the system phrase file whose index number is specified. @pos(line,column)@ -- Generates the ANSI escape sequence to position the cursor to the specified line and column. This operator is ignored if the user does not have ANSI support enabled. @privlev@ -- Inserts the user's "privilege security level". @pws@ -- Inserts a string indicating what type of personal file workspace the user is authorized to use. One of the following strings will be inserted: "None", "Temporary", "Permanent". See Chapter 8 for additional information about personal file workspaces. @pwsavail@ -- Inserts the remaining number of bytes available in the user's personal file workspace. @pwsdir@ -- Inserts the name of the user's personal workspace directory if a permanent directory has been assigned. Inserts nothing if the user does not have a permanent workspace directory. See Chapter 8 for additional information about personal file workspaces. @pwssize@ -- Inserts the total number of bytes that may be stored in the user's personal file workspace. "(unlimited)" is stored if there is no limit. See Chapter 8 for additional information about personal file workspaces. @qwkbbstime@ -- Inserts "Yes" if the QWK system is to use the BBS time for messages. Inserts "No" if the QWK system does not use the BBS time. @qwkbulletins@ -- Inserts "Yes" if QWK downloads are to include system bulletin files or "No" if bulletin files are not to be included. Chapter 3. Color and Substitution Operators 29 @qwkdloff@ -- Inserts "Yes" if QWK is configured to automatically logoff after downloads or "No" if auto logoff is disabled. @qwkdlempty@ -- Inserts "Yes" if QWK is configured to download empty packets or "No" if not. @qwkdllogoff@ -- Inserts "Yes" if QWK is configured to download the logoff message file or "No" if not. @qwknewfiles@ -- Inserts "Yes" if QWK is configured to download a list of new files or "No" if not. @qwkdlreplies@ -- Inserts "Yes" if QWK is configured to download the user's replies or "No" if not. @qwkdlwelcome@ -- Inserts "Yes" if QWK is configured to download the welcome file or "No" if not. @qwkincemail@ -- Inserts "Yes" if QWK is configured to download e-mail or "No" if not. @qwkincfiles@ -- Inserts "Yes" if QWK is configured to downloaded attached files or "No" if not. @qwklogoff@ -- Inserts "Yes" if QWK is configured to download the logoff message or "No" if not. @qwkmmp@ -- Inserts a count of the maximum messages per packet that QWK is configured to download. @qwkmma@ -- Inserts a count of the maximum messages per area that QWK is configured to download. @qwkmfs@ -- Inserts the size of the larges file that QWK is configured to download. @qwknews@ -- Inserts "Yes" if QWK is configured to download bulletin files or "No" if not. @qwknodlprmpt@ -- Inserts "Yes" if QWK is configured to suppress the download confirmation prompt or "No" if not. @qwknondx@ -- Inserts "Yes" if QWK is configured to skip creation of the NDF file or "No" if not. @qwkuloff@ -- Inserts "Yes" if QWK is configured to log off after an upload or "No" if not. @qwkwelcome@ -- Inserts "Yes" if QWK is configured to download the welcome file or "No" if not. @sysop1@ -- Inserts the name of the first (primary) sysop. @sysop2@ -- Inserts the name of the second sysop. Chapter 3. Color and Substitution Operators 30 @sysop3@ -- Inserts the name of the third sysop. @tagcount@ -- Inserts a number indicating the number of tagged files. @tagsize@ -- Inserts the size of all tagged files. @tagtime@ -- Inserts an estimate of how long it will take to download all of the currently tagged files. @tempdir@ -- Inserts the name of the temporary directory that the BBS creates to hold job-related files. This directory is also used to hold the DOOR.SYS file created by TSX-BBS when a door program is started. The temporary directory name is formed by using the base temp directory that is specified with the SYSOP program and then appending a subdirectory that is of the form "TMPnn" where "nn" is a "user identification number" that is unique for each user. @time@ -- Inserts the current time of day in the format hh:mm. @timeleft@ -- Inserts the number of minutes of time available for the current user. "Unlimited" is inserted if the user does not have a time limit. @timelimit@ -- Inserts the number of minutes of connect time that the current user is authorized to use each day. "Unlimited" is inserted if the user does not have a limit. @totalcalls@ -- Inserts a count of the total number of times that the user has called the BBS. @totaltime@ -- Inserts the total time that the user has been logged on during the current session in the form hh:mm:ss. @uploadcnt@ -- Inserts a count of the number of file uploads that the user has done. @uploadsize@ -- Inserts the total size of all files uploaded by the user. @user@ -- Inserts the user's first and last names separated by a space. @userid@ -- Inserts the user's BBS identification number. Each user is assigned a unique number when they are first authorized and they retain that same number until they are deleted from the BBS user list. Chapter 4 Conditional Expressions TSX-BBS allows the sysop to use conditional expressions to control many aspects of the board including which menu items appear and what privileges are required by users to access certain features. This feature is very powerful and allows the sysop to make the board appear quite different to some users than to others. The same syntax for conditional expressions is used throughout TSX-BBS so once you master it you can use it at many places. A conditional expression has the value true if it is non-zero or false if it is zero. Within a conditional expression you can use constants, comparison operators (greater-than, equal-to, etc.), logical operators, and special BBS-defined variables. Each of the privilege flags is a BBS-defined variable, as is the user's security level, and many other items such as the user's baud rate. As an example of a conditional expression consider a menu item that should only be presented to users who have ANSI capability and who are running at baud rates of at least 9600. The following lines would display the menu choice only in those cases: @if(ansi && baudrate >= 9600)@@eol@ Laser War @endif@@eol@ Within a conditional expression you can use built-in variables such as the ANSI and BAUDRATE variables shown in the previous example. These variables are assigned values by the system and are fully described in Section 4.3 starting on page 33. Some of the variables, such as ANSI, are true/false type variables with the values 1 (true) or 0 (false). For example, a simple test for ANSI capability could use the expression: @if(ansi)@ << done if ANSI capability >> @else@ << done if not ANSI capability >> @endif@ Other system variables have numeric values. For example, the BAUDRATE variable has the actual baud rate in bits per second (e.g., 2400, 14400, etc.). You can use the following comparison operators within conditional expressions. They produce the value 1 if the comparison is true or 0 if the comparison is false. 31 Chapter 4. Conditional Expressions 32 == Equal != Not equal <= Less than or equal >= Greater than or equal < Less than > Greater than For example, the following conditional expression tests to see if the user is connected at 9600 baud or faster. @if(baudrate>=9600)@ << User has a high baud rate >> @endif@ The following logical operators can be used in conditional expressions: ! Logical NOT (negates true and false) && AND || OR So, for example, the following conditional expression checks for users who have ANSI capability and are connected at 9600 baud or faster: @if(ansi && baudrate>=9600)@ << ANSI and 9600 baud or faster >> @endif@ Operator precedence, in decreasing order, is as follows: logical NOT, relational (comparison), logical AND ("&&"), logical OR ("||"). You may use parentheses in complicated expressions to group terms. For example, the following expression is true if the user has S1 privilege enabled or if he has S2 and S3: @if(S1 || (S2 && S3))@ << S1 or S2 and S3 >> @endif@ 4.1 Built-in Privileges TSX-BBS defines a number of "built-in" privileges that have predefined meanings. For a list of the current built-in privileges run the SYSOP program, select the User Authorization function, then select the user class function, and examine the entry for a class. You will see that the built-in privileges have textual names such as "Forum", "Mail", "Run doors", etc. and abbreviated names such as P00, P01, etc. The Pnn names can be used in your conditional expressions to test if a built-in privilege is enabled or disabled for the current user. For example, P02 is the privilege flag that allows users to download files, so the following expression would test to see if a user has download privilege: Chapter 4. Conditional Expressions 33 @if(P02)@ << User has download privilege >> @endif@ 4.2 Sysop-defined Privileges In addition to the built-in privileges which have predefined meanings, TSX-BBS allows the sysop to define up to 80 privileges. These sysop-defined privileges do not have any inherent meaning to the BBS system but may be used in conditional expressions. An example of a sysop-defined privilege might be the privilege given to some users allowing them to access adult oriented files. As with built-in privileges, sysop-defined privileges have both textual names and short names that are used in expressions. The short names have the form "Snn" where "nn" is a one or two digit sequence in the range 1 to 79. For example, the following conditional expression is true if the first sysop-defined privilege, S00, is enabled for the user: @if(S00)@ << User has S00 privilege >> @endif@ To define a sysop privilege run the SYSOP program and select the User Authorization function. Then type 'P' to select the Privileges function. You will then see the first of several pages of potential privilege entries. You will see that each privilege has an associated short name of the form "Snn" and a field where you can specify a textual name for the privilege. The textual name is just for your reference; it has no effect on the operation of the BBS. For example, if you wish to make S00 be an adult file library privilege, position the cursor to the start of the S00 privilege name field and type in something like "Adult files". Define any additional privileges that you wish and then press ESC to exit. Now, from the main User Authorization menu, select a user's entry and press Enter to examine it. Press Page Down a few times and you will come to a page that shows which privileges the user is authorized for. The left column shows built-in privileges and the right column shows sysop-defined privileges. You may set privileges to 'Y' to enable them or 'N' to disable them. 4.3 System Variables The following system variables may be used within conditional expressions: ANSI -- Has the value 1 if the user has ANSI terminal control capability or 0 if not. BAUDRATE -- The baud rate of the current user. The value is the actual data communications speed between the BBS and the caller's modem such as 14400, 2400, etc. This value is Chapter 4. Conditional Expressions 34 determined by examining the "CONNECT nnnnn" message returned by your modem when the connection is established. If your modem does not send in a connection speed message, then the value returned is the speed of the line between your computer's COM port and the modem rather than the modem-to-modem speed. COLOR -- Has the value 1 if the user has color display capability or 0 if not. CONSOLE -- Has the value 1 if the user is running at the console. Has the value 0 if the user is running through a serial communications line. DAY -- Day of the month in the range 1 to 31. DAYOFWEEK -- Day of the week. The value is 1 based so Sunday is 1 and Saturday is 7. DEMOBBS -- Has the value 1 if the TSX-32 system is not licensed to run TSX-BBS and the current user is running through a serial line. Has the value 0 if the TSX-32 system is licensed to run TSX-BBS or the current user is running at the console. DTESPEED -- Speed setting of the COM port through which the user is connected. This may be different than the BAUDRATE variable that indicates the actual modem-to-modem speed. EXISTS(filename) -- If the specified file exists then the value is 1; otherwise the value is 0. GROUP -- The group number for the user. The group number can be assigned using the SYSOP program. It is intended to identify the user with a company or other organization. For example, the following conditional expression would select only those users who are in group 46: "GROUP==46". HOUR -- Hour of the day in the range 0 to 23. For example, the following expression is only true between 1AM and 6AM: "HOUR>=1&&HOUR<6". IBMCHAR -- Has the value 1 if the user can display IBM graphics characters or 0 if not. MINUTE -- Minute of the hour in the range 0 to 59. MONTH -- Month number in the range 1 to 12. NEWFILE(filename) -- If the specified file exists and its creation date is newer than the date when the user last logged on, then the value is 1; otherwise the value is 0. NODE -- Terminal line number. Chapter 4. Conditional Expressions 35 PHONELINE -- Has the value 1 if the user is connected through a dial-up phone connection. Has the value 0 for hardwired connections. PRIVLEV -- The sysop may assign a privilege "security level" to users. This value may be in the range 0 to 999. The TSX-BBS system does not make use of the security level but you can use it in conditional expressions. QWKSERVICES -- Has a count of the number of defined QWK services. TAGCOUNT -- Has a count of the number of files that are currently tagged and waiting to be downloaded. TELNET -- Has the value 1 if the user is connected through an incoming Telnet connection. The value is 0 if the user is connected through a dial-in phone connection or is running the BBS from the system console. YEAR -- The current year including the century (e.g., 1994). 4.4 Conditional Expressions in Menus and Text There are many places where conditional expressions can be used to control the operation of the bulletin board. One such place is within text that is displayed to the user. This text may be used in a menu, a message such as a logon greeting, or a status update message. The @if(expression)@, @else@, and @endif@ substitution operators are used for conditional control of text. When TSX-BBS encounters a @if(expression)@ substitution operator it evaluates the 'expression' value and if the expression value is false (0) begins skipping text. The skipping continues until an @endif@ or @else@ operator is found in the text. For example, consider the following display line. You @if(ansi)@have@else@do not have@endif@ ANSI capability. When the @if(ansi)@ expression is found, TSX-BBS checks to see if the current user has ANSI control capability. If so, text processing continues with the next character and the word "have" is displayed. If the @if(ansi)@ expression is false, then text is skipped up to the @else@ operator and the text that follows it ("do not have") is displayed. In many cases you may wish to use conditional operators to select whole lines of text. For example, consider the following text: Chapter 4. Conditional Expressions 36 Capability summary: @if(ansi)@ You have ANSI capability. @else@ You do not have ANSI capability. @endif@ @if(color)@ You have color capability. @else@ You do not have color capability. @endif@ This displays different lines depending on whether the user has ANSI and color capability. However, this may not do exactly what you want. The problem is that if the @if(ansi)@ expression is true, text processing continues and the carriage-return and line-feed characters at the end of the line containing @if(ansi)@ are displayed. A similar problem occurs on the @else@ and @endif@ lines. The result is that you end up with extra blank lines in the displayed text. The proper way to do this is to use the following commands: Capability summary: @if(ansi)@@eol@ You have ANSI capability. @else@@eol@ You do not have ANSI capability. @endif@@eol@ @if(color)@@eol@ You have color capability. @else@@eol@ You do not have color capability. @endif@@eol@ The @eol@ operator means "end of line". It terminates text processing for the line immediately; any characters that follow it, including the carriage-return and line-feed at the end of the line, are ignored. You may nest @if()@, @else@, and @endif@ operators. If an @if()@ operator is false, TSX-BBS skips all text, including other @if()@ and @endif@ operators until it finds the matching @else@ or @endif@ operator. Similarly, if an @else@ operator is found that begins skipping, the skipping continues until the matching @endif@ operator is found. Chapter 5 Menu Compiler One of the key features of the TSX-BBS is that it allows you easily to create and customize menus. You can select the placement of items on menus, the colors, and limit displayed items based on user classes and privileges. The TSX-BBS MENU program is a compiler that reads a menu description source file that you create using an ASCII editor, and produces a compiled menu object file that can be executed efficiently by the BBS system. The BBS menu design language includes a rich set of commands and actions to make it easy for you to design menues and look good and perform a wide variety of actions. 5.1 Using the Menu Compiler The menu compiler is a program named MENU.EXP. This file should be placed in a directory that is part of your search path. The command to compile a menu has the form MENU source_file [object_file] where "source_file" is the name of the menu source description file. The default extension for these files is ".MNU". The "object_file" argument specifies the name of the menu object file that is to be created. If you do not specify an object file, the menu compiler creates a file with the same name as the source file but with the extension ".TMU". For example, the following command compiles a menu file named "files.mnu" and produces an object file named "files.tmu": menu files 5.2 Introductory Example Before getting into the details of menu design, lets look at a simple example menu which could be used to control the E-mail operations of the BBS: 37 Chapter 5. Menu Compiler 38 $name Main menu $hot $prompt Choice: $display @cls@ @menutitle(Mail Menu)@ `Message to SYSOP `Write message `Read messages `Filing cabinet `Synonyms `Address book `Quit $item key=M action=mailsysop $item key=W action=mailsend $item key=R action=mailrecv $item key=F action=mailfile $item key=S action=mailsyn $item key=A action=mailabook $item key=Q action=return $item key=(other) action=return Each section of the menu description begins with a command that has '$' as its first character. The first command,"$name", declares a phrase to be displayed as the activity for user while running the menu. The next command, "$hot", indicates that "hot keys" (single characters) are to be used to make menu selections. The "$prompt" command indicates that the word "Choice:" is to be displayed at the bottom of the menu to prompt the user to type a command key. The "$display" command begins the section of the menu that has the text that is to be displayed as the menu. All of the lines following $display up to the first $item command are displayed on the user's screen as the text of the menu. Within the display text you may use text substitution operators such as "@cls@" to clear the screen. Within the display text, you can use the accent character (`) in front of characters that you wish to have highlighted as hot key characters. The BBS system displays these characters in a different color and encloses them in brackets. In this example, the 'M' of "Message to Sysop" and the 'W' of "Write message" will be highlighted. The $item commands tell the menu compiler what action to take when various keys (or commands) are entered. In this example the 'M' key invokes an action named "mailsysop". This particular action is built into the BBS, but you have the option of invoking other menus that you write or running TPL programs. Each of the menu commands is described in detail in sections that follow. Chapter 5. Menu Compiler 39 5.3 $name -- Activity name for menu The $name command declares a name string that is displayed as the current activity for the user while the menu is active. The form of the command is $name name_string Where "name_string" is one or more words to be displayed as the users activity. The $name command is optional; if it is omitted the name of the menu file is used as the activity name. 5.4 $hot -- Single character activation The $hot command tells the BBS compiler that menu actions are to be triggered by pressing a single key without having to type Enter. The $hot command is ignored if any of the keys declared in $item commands are more than a single character long. If you do not specify $hot, the user will have to press Enter after entering the command key. 5.5 $prompt -- Prompt string The form of the $prompt command is $prompt command where "command" is a word or phrase that is to be displayed at the bottom of the menu to prompt the user to type a key or command. If you do not provide a $prompt command the "MPROMPT" phrase is used as the default. The default english prompt is "Command:". For example, the following command would cause "Make a selection:" to be displayed as the prompt: $prompt Make a selection: 5.6 $display -- Display text for menu The $display command begins the section of the menu that has the text to be displayed. There are two forms of the $display command. The first form is $display file where "file" is the name of a separate file that contains the text of the menu to display. This form of the command is useful if you wish to use an ANSI editor or some other program to help you construct your menu text. For example, the following command causes a file named "voting.txt" to be displayed for the menu: $display c:\bbs\voting.txt Chapter 5. Menu Compiler 40 The display file may include text substitution and color change operators. You should specify the device and directory where the file is located. The second form of the $display command is used when you wish to include the text as part of the menu description file. This form of the command is: $display << text to display>> $<< next command >> Note that there is no file name on the $display command line. The text to be displayed begins on the line following the $display command and continues on subsequent lines down to the next menu command that begins with a dollar sign. The following is an example of this form of the command: $display @cls@ @menutitle(Mail Menu)@ `Message to SYSOP `Write message In addition to text substitution operators such as "@cls@" and color change operators such as "@X07", you can use the accent character to mark letters that are to be highlighted as hot keys. Note, the accent character is not the apostrophe. On most keyboards the accent character is on the top left key with the tilde character. In this example the 'M' of "Message to sysop" and the 'W' of "Write message" will be highlighted. The highlighting consists of using a different color for the letter and enclosing it in brackets. The use of the accent character to mark hot characters is optional. Other than changing the display of the character it does not affect the operation of the menu. Note that the actual characters that cause actions to take place are specified by the $item commands and are affected by which characters are highlighted. The "@menutitle(text)@" text substitution command may be used to create menu title lines. The text in the parentheses is displayed in the standard title color and is enclosed in a box. You may not use text substitution commands within the text string. You can also use @if(expression)@, @else@, and @endif@ commands within the display portion of a menu to control which items are to be displayed. Section 4.4 on page 35 explains the @if()@ operator. The following is an example of a menu that only displays the chat item to users who have the P8 privilege enabled: Chapter 5. Menu Compiler 41 `Electronic mail `Discussion Forums @if(p8)@@eol@ `Chat @endif@@eol@ `Who is on You can use text substitution operators and @if()@ operators in the display text if it is part of the menu file or if it is in an external file. 5.7 $item -- Action item The $item command is used to specify what action is to be taken when menu selection keys and commands are entered. The form of this command is $item option1 option2 option3 ... where "option1", etc. are optional clauses described in the following sections. Long $item commands can be continued across multiple lines. The command ends when the next line is encountered that begins with a command keyword. The following is an example of a $item command that spans two lines: $item key=C action=logwrite(Play Chess); door("c:\pchess\pchess.cmd","Beginning Chess") if(S8) 5.7.1 key -- Character or command The key clause specifies which hot key or command is to trigger the associated action. The key and commands are not case sensitive. The form of this clause is key=string where "string" is the letter or command that the user is to type to cause the associated action to occur. You may enclose the command string in quote signs if it contains a space; otherwise, the command string ends at the first space, tab, or the end of the line. The following is an example of a $item that lists the users on-line when a space is typed: $item key=" " action=who There is a special action key named "(esc)" that corresponds to the Esc (escape) key. For example, the following set of actions return when either the letter 'Q' or ESC is pressed: $item key=Q action=return $item key=(esc) action=return Chapter 5. Menu Compiler 42 One, and only one, $item command may have a key clause with the "(other)" specification. If such a $item command is provided, the specified action is taken if there is no other $item command that matchs the command string that the user enters. The $item with "key=(other)" must be the last $item. If there is no "(other)" type item and a key is pressed that is not defined by some $item, then the bell is rung and no action is performed. The following are examples of key clauses. $item key=Q action=return $item key=(esc) action=return $item key="SEND MAIL" action=tpr("mail") $item key=(other) action=return 5.7.2 if -- Conditional item The "if" clause allows you to specify actions that are only available if certain conditions are met. The form of the if clause is if(expression) Where "expression" is a logical expression including items described in Chapter 4 starting on page 31. For example, the following $item command will be triggered when the user types 'A' only if the user has 'p1' privilege: $item key=A if(p1) In some cases it is useful to have the same letter perform different actions depending on the class or privileges of a user. For example, a BBS that offers an adult picture section may want to begin a file browse when 'A' is typed by properly authorized users, but for other users it may want to display an explanation file. To do this, use multiple $item commands with the same "key=string" clauses but with if clauses that control which privileges are required to invoke the command. Since the $item commands are scanned in the order in which you write them, the first $item that meets the requirements of its if clause is executed. In the following example the fallist action is invoked when users with 'p1' privilege type 'A' but all other users invoke the dispfile action: $item key=A if(p1) action=fallist(bbs:adult,"Adult files") $item key=A action=dispfile(bbs:noadult.txt) 5.7.3 action -- Menu action The action clause specifies which action is to be taken when the associated key or command is entered. The form of this clause is action=name where "name" is the action keyword name. Some of the actions are simple words such as "return" and "exit". Other actions require Chapter 5. Menu Compiler 43 one or more argument values. Arguments are specified in parentheses following the action keyword. If there is more than one argument, separate the arguments with commas. If an argument has a comma as part of its text, enclose it in quote signs. The following are example actions: $item key=Q action=return $item key=G action=offcheck $item key=F action=menu(\bbs\file) $item key=D action=display("Sorry, you can't do this") $item key=L action=fallist(bbs:master,"All file areas") 5.7.3.1 Combined actions It is also possible to cause more than one action to be performed when a key is pressed. To do this specify multiple action keywords after "action=" and separate the keywords with semicolons. For example, the following command writes a string to the BBS log file and then enters a submenu named "business": $item key=B action=(Entering business);menu(business) If the set of items is too long for one line you may continue on to subsequent lines. The following sections describe each available action. 5.7.3.2 actname -- Set activity name The BBS maintains an "activity" name for each user that indicates what sort of operation the user is currently doing. The activity name is automatically set to the name of a menu when the menu is entered; other activity names such as "Upload" and "Download" are set as actions are performed. The actname action allows you to set an activity name on your own. The form of the action is action=actname(name) Where 'name' is an activity name that may be up to 16 characters long. 5.7.3.3 autologoff -- Do count down and then logoff The autologoff action displays a message telling the user that the auto-logoff sequence has been started. It then displays a count down that shows the number of seconds remaining until the log off will occur. If the user types a key during the count down, the log off is aborted and control returns to the menu. If no key is pressed, the user is logged off. The form of the action is action=autologoff Chapter 5. Menu Compiler 44 5.7.3.4 bbsexit -- Exit from BBS to TSX The bbsexit action is similar to the logoff action in that it causes the user to log off of the BBS. However, bbsexit leaves the user connected to the computer after exiting from the BBS so that the user can execute TSX system commands and run programs other than the BBS. This is useful for sysops who wish to exit from the BBS so that they can run the SYSOP control program or other programs. However, it is vital that the use of this action be limited to properly authorized users because once a user has exited from the BBS to the TSX system they can execute commands such as "DEL *.*" which could cause great harm to the system. The form of the action is action=bbsexit 5.7.3.5 brfile -- Browse text file The brfile action permits the user to browse the contents of an external text file such as a help file or list of phone numbers for the board. It is similar to the dispfile menu action. The brfile action permits the user to move forward and backward in the file whereas dispfile does not. However, dispfile permits substitution constructs in the text whereas brfile does not. 5.7.3.6 chathandle -- Change chat handle The chathandle action displays the user's current chat handle and then prompts the user for a new handle. The form of the action is action=chathandle 5.7.3.7 chatjoin -- Join a chat group The chatjoin action displays a list of the currently active chat groups and allows the user to select which one to be joined. The form of the action is action=chatjoin 5.7.3.8 chatmake -- Create a chat group The chatmake action prompts the user for the name of a chat group that is to be created, makes the group, and then enters the user into the group. The form of the action is action=chatmake 5.7.3.9 chatuser -- List users in chat The chatuser action displays a list of the users that are currently participating in chat. The form of the action is action=chatuser Chapter 5. Menu Compiler 45 5.7.3.10 datesearch -- Search for files by date The datesearch action begins the BBS operation that searches a file area for all files created since a specified date. The user is prompted to enter the date. The form of the action is action=datesearch(falname[,fdlname]) where 'falname' is the name of the FAL file containing the area descriptions and 'fdlname' is the name of the FDL file that contains the file descriptions to be searched. If you omit the 'fdlname' argument then all FDL files listed in the FAL file are searched. For example, the following action searches files in a FDL list called "bbs:swim" that is part of a FAL area called "bbs:master": action=datesearch(bbs:master,bbs:swim) whereas the following action searches all FDL files contained in the bbs:master FAL: action=datesearch(bbs:master) 5.7.3.11 dirupload -- Upload files to a directory The dirupload action prompts the user for the names of one or more files to be uploaded and places the uploaded files into the directory whose name you specify as an argument to the dirupload action. This action does a "raw" file upload and does not update any information in any file description file (fdl file). Use the fdlupload action to upload files and accept descriptions for fdl files. The form of the action is action=dirupload(dirname) where 'dirname' is the name of the directory where uploaded files are to be placed. 5.7.3.12 dispfile -- Display a file The dispfile action displays a file. The form of this action is action=dispfile(file_name[,subcmd]) where "file_name" is the specification for the file to be displayed. The file is displayed and a prompt, "- press a key to continue -", is presented at the end. The 'subcmd' argument controls whether substitution operators of the form "@word@" are processed if they are found in the text of the file. If the 'subcmd' argument is omitted or a value of 1 (true) is specified for it, then embedded substitution commands are replaced by the appropriate system-supplied text strings. If 0 (zero) is specified for 'subcmd' then at-signs in the file are treated as ordinary characters rather than command delimiters. Chapter 5. Menu Compiler 46 Also see the brfile menu action, described on page 44. 5.7.3.13 display -- Display a string The display action displays a string on the user's screen. The form of the action is action=display(string[,subcmd]) where "string" is the text string to be displayed. The "subcmd" argument controls whether substitution operators of the form "@word@" are processed if they are found in the text of the file. If the "subcmd" argument is omitted or a value of 1 (true) is specified for it, then embedded substitution commands are replaced by the appropriate system-supplied text strings. If 0 (zero) is specified for "subcmd" then at-signs in the file are treated as ordinary characters rather than command delimiters. For example, the following $item command displays "You are not privileged for this" when the user types 'A'. The "pause" menu action is similar to this one but pauses until the user types a key after displaying the message. $item key=A action=display(You are not privileged for this) 5.7.3.14 door -- Run door program The door action begins execution of an external "door" program. The form of the action is action=door(cmdline[,message[,activity]]) where 'cmdline' is the command line that is to be passed to the TSX command interpreter to execute the door batch file. The 'message' argument is optional. If specified, it is a string that is displayed in a box while the door is being started. You can specify something like "Starting chess" to give the users something to look at while the door is getting started. The 'activity' argument is also optional. If specified, it is a string to be displayed as the current activity for the user while the door is running. You can specify arguments after the command file name. The "@node@" substitution operator can be used to pass the TSX line number as an argument to the command file. The @userid@ substitution operator passes the user's BBS identification number. Each user has a unique identification number. The "@tempdir@" substitution operator can be used to pass the name of the temporary directory where the DOOR.SYS file is created. For example, the following example executes a door command file named "c:\chess\pchess.cmd" and passes the line number and temporary file directory as arguments: $item key=C action=door("c:\chess\pchess.cmd @node@ @tempdir@") Chapter 5. Menu Compiler 47 See Section 14.4 on page 136 for more details about the door action. 5.7.3.15 download -- Download a file The download action downloads a file from the BBS to the user's computer. The form of the action is action=download(filename) where 'filename' is the specification for the file to be downloaded. For example, the following action downloads the file "bbs:filelist.dat": action=download(bbs:filelist.dat) 5.7.3.16 exit -- Exit from menus The exit action causes the current set of menus to exit and return control to the TPL program that invoked them. When the exit action is performed control returns to the invoking TPL program regardless of the current menu call nesting depth. The form of the action is action=exit 5.7.3.17 fallist -- Display file area list The fallist action displays a list of file areas. The form of the action is action=fallist(falname,heading) where 'falname' is the name of the FAL file containing the area descriptions and 'heading' is a string to be displayed at the top of the selection list. For example, the following action displays a list of files described by the "bbs:master.fal" file and prints "All file areas" as the title: action=fallist(bbs:master,"All file areas") See Chapter 7 for additional information about setting up file areas. 5.7.3.18 falsearch -- Search file descriptions The falsearch action invokes the BBS subsystem that searches file descriptions for a text string that the user enters. This action performs "global" searches that span multiple file sets. The form of this action is action=falsearch(falname,heading) where 'falname' is the name of the FAL file containing the list of files (and/or subareas) that are to be searched, and 'heading' is a string to be displayed during the search. For example, the Chapter 5. Menu Compiler 48 following action searches all files defined by the bbs:master.fal fal file and displays "All file areas" as the search heading: action=falsearch(bbs:master,"All file areas") 5.7.3.19 fdllist -- List files in an FDL The fdllist action causes the BBS to list the descriptions of the files in a specified File Description List (FDL) that is part of a File Area List (FAL). The specified FAL file must have an entry for the specified FDL file. As the names are listed the user is provided options such as tagging, downloading, searching, etc. The form of the action is action=fdllist(falname,fdlname) where 'falname' is the name of the FAL file and 'fdlname' is the name of the FDL file. For example, the following action lists all files in the bbs:swim.fdl file that is part of the bbs:master.fal area: action=fdllist(bbs:master,bbs:swim) 5.7.3.20 fdlsearch -- Search through file list The fdlsearch action prompts the user to enter a word or phrase to search for and then searches through the file descriptions in a specified FDL file that is part of a specified FAL area. Files that have the matching word or phrase in their names or descriptions are listed and the user may tag and/or download them. The form of the action is action=fdlsearch(falname,fdlname) where 'falname' is the name of the FAL file area file and 'fdlname' is the name of the file description file. This action differs from the falsearch action in that falsearch searches all file descriptions that are in all file sets and subcategories of a specified category, whereas fdlsearch searches only a specified file set. 5.7.3.21 fdlupload -- Upload a file The fdlupload action begins a sequence that prompts the user for a file name and description and then uploads the file to the bulletin board and enters the description into a specified FDL file. The form of the action is action=fdlupload(falname,fdlname) where 'falname' is the name of a File Area List (FAL) file that includes the FDL file, and 'fdlname' is the name of a File Description List (FDL) file into which the description for the file being uploaded is stored. For example, the following action begins Chapter 5. Menu Compiler 49 an upload. The file description is placed in a file named "bbs:newfiles.fdl". The File Area List (FAL) is "bbs:master.fal". action=fdlupload(bbs:master,bbs:newfiles) 5.7.3.22 fmpmenu -- Display file transfer protocol menu The fmpmenu action displays a menu from which the user can select the file transfer protocol (X-modem, Y-modem, or Z-modem) to be used for subsequent file transfers. The form of the action is action=fmpmenu 5.7.3.23 fmpset -- Set file transfer protocol The fmpset action sets the file transfer protocol for the current user. The form of the action is action=fmpset(name) where 'name' is XMODEM, YMODEM, or ZMODEM. 5.7.3.24 forumcheck -- Check for pending forum messages The forumcheck action checks to see if the user has any unread forum messages. If so, it allows the user to read the messages. The form of the action is: action=forumcheck(notify) The 'notify' argument controls how the action prompts the user. It can have three values: 0 -- If the user has pending messages, a message is printed telling the user about this and asking the user if he or she wants to read the messages. If there are no pending messages, the action does nothing and no message is printed. 1 -- Operates the same as value 0 except if there are no pending messages a message is printed telling the user that there are no pending messages. 2 -- If the user has pending messages, the first message is immediately displayed without asking the user if he or she wants to read it. If there are no pending messages, a message is printed telling the user that there are no pending messages. 5.7.3.25 frmalist -- Display alphabetic list of forums The frmalist action begins forum processing. It displays the current list of forums in alphabetical order. This is one of the primary ways that the users see the forum list. It accepts an optional argument which is allows the sysop to restrict the display to certain grand divisions or other names. Chapter 5. Menu Compiler 50 The forum of the action is action=frmalist([rootname]) If the rootname argument is not specified then all forums which the user has read access to will be displayed. If the rootname argument is "usenet", for example, this display would only select forums which began with "usenet". The name can be as long as desired; the rootname argument "usenet.comp.ibm.hardware" would restrict the display to forums which begin with "usenet.comp.ibm.hardware". 5.7.3.26 frmdownload -- Downloaded selected messages The frmdownload action initiates download processing for a previously selected list of items. This is not the same as QWK processing. QWK processing involves logging on, cycling through a preselected list of forums, collecting new messages and uploading replies, and logging off. There is another way to download a message or messages. When viewing messages and topics interactively the user is allowed to tag topics and messages for download. Each of these tagged items is placed on a list of items to be downloaded later. The user can select a number of messages in various forums. This occurs interactively, not on a batch basis like QWK. The forums need not be QWK forums. Once the user is finished this function allows the user to download the selected items. The form of the action is action=frmdownload() 5.7.3.27 frmenter -- Enter the forum name hierarchy The frmenter action allows the user to invoke the hierarchical forum display. This display shows the forum names in categorical form. In this display the users can view the names at a certain level in the category and move up and down to different categorical levels. The optional argument allows the sysop to specify the base of the display. The form of the action is action=frmenter([rootname]) If a rootname argument is not specified the display will initially consist of the set of grand division names which the user has read access to. If the rootname argument is "usenet", for example, this display would consist of the entries under "usenet". The name can be as long as desired; the rootname argument "usenet.comp.ibm.hardware" would restrict the display to forums under "usenet.comp.ibm.hardware". Chapter 5. Menu Compiler 51 5.7.3.28 frmgetlist -- Download list of forums The frmgetlist action allows the user to download a list of forum names. The form of the action is action=frmgetlist([rootname]) The list will be in an ascii file and will contain the forum name as well as the forum number. The list will only contain forum names which the user has read access to. The user may download the file as an ascii or compressed file and is prompted for this choice. There is an optional argument which can restrict which forums can be selected for listing. If the rootname argument is not specified then all forums which the user has read access to will be collected. Otherwise only those forums which begin with the root name and which the user has read access to will be collected. If the rootname argument is "usenet", for example, this action would only collect forum names which began with "usenet". The name can be as long as desired; the rootname argument "usenet.comp.ibm.hardware" would collect forums which begin with "usenet.comp.ibm.hardware". 5.7.3.29 frmslist -- Search for list of forums The frmslist action allows the user to search for a set of forums whose names contain certain specified keywords. The user is prompted for a search expression. This search expression is used as the basis for the search. The resulting list can then be browsed in the same way that the hierarchical or alphabetical list can be browsed. There is an optional argument which is the root name to be used in the search. This allows the sysop to restrict searches to certain grand divisions or other categories. If the rootname argument is "usenet", for example, this display would consist of the entries under "usenet" which also match the search string. The name can be as long as desired; the rootname argument "usenet.comp.ibm.hardware" would restrict the display to forums under "usenet.comp.ibm.hardware" which also match the search string. The form of the action is action=frmhlist([rootname]) Chapter 5. Menu Compiler 52 5.7.3.30 frmentnum -- Enter a forum by number The frmentnum action allows the user to enter a forum by number. If no argument is specified the user is prompted for the forum number to enter. The forum number can be specified as an argument to allow the sysop to define an action which will enter a specified forum number with no additional user intervention. The form of the action is action=frmentnum([number]) 5.7.3.31 frmentname -- Enter a forum by name The frmentname action allows the user to enter a forum by name. If no argument is specified the user is prompted for the forum name to enter. The forum name can be specified as an argument to allow the sysop to define an action which will enter a specified forum name with no additional user intervention. The form of the action is action=frmentname([name]) 5.7.3.32 frmprefix -- Enter forum by name with prefix The frmprefix action is similar to the frmentname action except that it allows a an optional prefix to be specified by the sysop. This string is prepended to the name specified by the user. This is useful for allowing the user to enter a named forum without typing in the entire name. The difference between the two is that frmprefix always prompts the user while frmentname will not prompt the user if a name is specified. Using frmprefix without a prefix is identical to using frmentname without an argument; both prompt the user for the full forum name. The form of the action is action=frmprefix([prefix]) 5.7.3.33 frmqwkman -- Manage QWK forum list The frmqwkman action displays a list of the forums that the user has currently selected for QWK downloads and allows the user to add and delete forums. The form of the action is: action=frmqwkman 5.7.3.34 ftp -- Invoke Internet FTP File Transfer Program The ftp action invokes the FTP (File Transfer Protocol) program used for sending and receiving files through the Internet. The form of the action is actin=ftp([command_file]) where the 'command_file' argument is optional. If specified, it is the name of a file with FTP commands that are executed when FTP Chapter 5. Menu Compiler 53 starts running. If this argument is omitted, the user is prompted to enter the name of the host site to be accessed, the user name and the password to use for the logon. 5.7.3.35 logoff -- Log off the BBS The logoff action records usage information about the current user in the appropriate accounting files, logs the user off the BBS, and hangs up the phone line. The form of the action is action=logoff 5.7.3.36 logwrite -- Write message to BBS log file The logwrite action writes a message to the BBS log file named "bbs:bbs.log". The form of the action is action=logwrite(message) This function is frequently used with another action by combining the two actions as described in Section 5.7.3.1 on page 43. For example, the following command writes a log entry and then invokes a sub-menu named "business". $item key=B action=(Entering business);menu(business) 5.7.3.37 mailabook -- Manage address book The mailabook action invokes the address book management functions of the BBS e-mail system. The user is presented with a screen that allows him to add, delete, and alter address book entries. The form of the action is action=mailabook 5.7.3.38 mailbrowse -- Browse message base The mailbrowse menu action is intended to be used only by the sysop. It presents the contents of any message base in the same format as that used for the mail filing cabinet. However, every non deleted message in the message base is shown, regardless of the sender or recipient. 5.7.3.39 mailcheck -- Check for pending mail messages The mailcheck action checks to see if the user has any unread E-mail messages. If so, it allows the user to read the messages. The form of the action is: action=mailcheck(notify) The 'notify' argument controls how the action prompts the user. It can have three values: Chapter 5. Menu Compiler 54 0 -- If the user has pending messages, a message is printed telling the user about this and asking the user if he or she wants to read the messages. If there are no pending messages, the action does nothing and no message is printed. 1 -- Operates the same as value 0 except if there are no pending messages a message is printed telling the user that there are no pending messages. 2 -- If the user has pending messages, the first message is immediately displayed without asking the user if he or she wants to read it. If there are no pending messages, a message is printed telling the user that there are no pending messages. 5.7.3.40 mailfile -- Manage filing cabinet The mailfile action invokes the filing cabinet management functions of the BBS e-mail system. The user is presented with a screen that allows him to add, delete, and read filed messages. The form of the action is action=mailfile 5.7.3.41 mailrecv -- Receive messages The mailrecv action invokes the BBS mail receive subsystem that allows the user to browse through and read pending incoming e-mail messages. The form of the action is action=mailrecv 5.7.3.42 mailsend -- Send a message The mailsend action invokes the BBS subsystem that accepts and sends an e-mail message. The user is prompted for the recipient's name and subject and then the mail composition editor is invoked to accept the message to be sent. The form of the action is action=mailsend 5.7.3.43 mailsyn -- Manage synonymous names The mailsyn action invokes the synonymous name management functions of the BBS e-mail system. The user is presented with a screen that allows him to add, delete, and alter his synonymous mail names. The form of the action is action=mailsyn Chapter 5. Menu Compiler 55 5.7.3.44 mailsysop -- Send message to sysop The mailsysop action invokes the BBS mail subsystem to send a message to the sysop. The sysop's name is automatically specified as the recipient of the message. The mail composition editor is invoked to accept the message to be sent. The form of the action is action=mailsysop 5.7.3.45 menu -- Call a menu This action invokes a submenu. The form of the action is action=menu(menu_name) where "menu_name" is the file specification for the menu to be invoked. You should specify the device and directory with the name. The default extension is ".TMU". Control returns to the calling menu when the called menu executes a return action. For example, the following action invokes a menu file named "\bbs\files.tmu": action=menu(\bbs\files) 5.7.3.46 menujump -- Jump to a menu The form of the menujump action is action=menujump(menu_name) where "menu_name" is the file specification for the menu to be invoked. You should specify the device and directory with the name. The default extension is ".TMU". The menujump action is very similar to the "menu" action -- it invokes another menu. The difference is that the 'menu' action calls a menu in such a way that when the called menu exits control returns to the calling menu whereas menujump transfers control to the specified menu without setting up return information. When the menu that is being entered executes a 'return' action, control is transfered to any higher level menu rather than returning to the menu that did the menujump action. In essence, the menu being entered is considered to be a continuation of the menu executing the menujump action. For example, assume there are three menus named m1, m2, and m3. The m1 menu uses the 'menu' action to call m2. The m2 menu uses the menujump action to invoke m3. When m3 executes a 'return' action, control returns to m1 rather than m2. If, on the other hand, m2 had used a 'menu' action to invoke m3, then when m3 returned control would go back to m2. Chapter 5. Menu Compiler 56 5.7.3.47 namesel -- Select files for download by name The namesel action prompts the user to enter the name of a file that is to be selected for downloading. The user is allowed to enter multiple names. The form of the action is action=namesel([falname[,fdlname]]) where the optional 'falname' argument is the name of the FAL (file area list) file that describes the areas to be searched. If you do not specify any arguments, BBS:MASTER.FAL is used as the default FAL file name. The second argument, 'fdlname', is also optional. If it is not specified, all files in all areas described by the FAL file are searched. If you specify an FAL and FDL file, only files in the area described by the FDL are searched. For example, to allow the user to search for a file in all areas simply use the menu item: action=namesel To search only the files in the BBS:IBMUTIL.FAL area that is under the BBS:MASTER.FAL file, use the following action: action=namesel(BBS:MASTER.FAL,BBS:IBMUTIL.FAL) 5.7.3.48 offcheck -- Confirm and then logoff The offcheck action is very similar to the logoff action that logs a user off. The difference is that logoff does an immediate log off whereas offcheck prints a message of the form "Do you want to log off? (Y/N):" and allows the user to enter 'Y' or 'N'. If the user enters 'Y', or presses Enter, the user is logged off. If the user enters 'N' he is not logged off. action=offcheck 5.7.3.49 offquiet -- Log off without message The offquiet action logs the user off without displaying the usual message telling the user how much time he has used. It is a silent logoff. 5.7.3.50 pagesysop -- Page the sysop The pagesysop action sends paging messages to the console terminal to notify the BBS sysop that a user would like to engage in a conversation. The "chat" function of the dashboard menu of the SYSOP program can be used to respond to a page and commence a conversation. The pagesysop function checks to see if the sysop has disabled paging and, if so, notifies the user without sending a paging message. If you wish to disallow sysop paging entirely, it is best to not offer a paging menu choice. Chapter 5. Menu Compiler 57 5.7.3.51 pause -- Display a string and pause The pause action displays a string on the user's screen followed by by the message "-press a key to continue-". The form of the action is action=pause(string) where "string" is the text string to be displayed. For example, the following $item command displays "You are not privileged for this" when the user types 'A'. $item key=A action=pause(You are not privileged for this) You may omit the argument string in which case the action prints only the "-press a key to continue-" message. 5.7.3.52 print -- Display a string The print action is equivalent to the display action. The form of the action is: action=print(string) 5.7.3.53 pws -- Manage personal file workspace The pws action invokes a browse screen showing the files that are currently stored in the user's "personal file workspace". This workspace is used as a repository for files being send and received using FTP and it can also be used as a general file storage area. See Chapter 8 for additional information about personal file workspaces. The form of the action is action=pws 5.7.3.54 qwkcfg -- Set QWK configuration options The qwkcfg menu action displays a menu and allows the user to set QWK configuration options such as whether they want e-mail messages downloaded. The text of the menu is stored in the file bbsbin:qwkcfg.mnu. You may alter it and alter the entry in the BBS language phrase file with the label QWKCFG. The form of the action is: action=qwkcfg 5.7.3.55 qwkdownload -- Download QWK packet with messages The qwkdownload action causes the TSX-BBS QWK system to collect all messages from QWK selected forums, create a compressed packet, and download the packet to the user. The form of the action is: action=qwkdownload(personal) Chapter 5. Menu Compiler 58 where the 'personal' argument is optional. If the 'personal' argument is omitted or 0 is specified for it, all messages in the selected forums are downloaded. If 1 is specified for the argument then only messages addressed to the user are downloaded. 5.7.3.56 qwkservices -- Select services The qwkservices action allows the user to select which service files are to be included in downloaded QWK packets. A menu is displayed showing each available service and the user can select which ones are wanted. The form of the action is: action=qwkservices 5.7.3.57 qwkupload -- Upload a QWK packet The qwkupload action causes TSX-BBS to prompt the user to begin uploading a QWK packet with outgoing messages. The form of the action is action=qwkupload 5.7.3.58 qwkread -- Read new messages from forums The qwkread action is a discussion forum action that begins reading all new messages that have been posted in forums selected for QWK reading by the user. Note: This action does not cause a QWK download, it initiates on-line reading of the new messages in those forums that have been selected for QWK processing. The form of the action is action=qwkread 5.7.3.59 return -- Return from menu call The 'return' menu action causes the current menu to exit passing control to the next higher level menu that invoked the current menu with a 'menu' action (see Section 5.7.3.45). If the top most menu executes a 'return' action, control is passed to the TPL program that invoked the top level menu just as if an 'exit' action had been invoked. 5.7.3.60 setclass -- Change user class The setclass action changes the class of the current BBS user to a specified class. The form of the action is action=setclass(class) where "class" is the class name. The SYSOP program is used to define classes. A class may control privileges and other attributes for the user. When the setclass action is executed, the privileges and other parameters are immediately changed to those associated with the named class. The user's authorization record is also changed so the new privileges and other attributes will Chapter 5. Menu Compiler 59 continue to be in effect for future logons. For example, the following action changes the user class to "paid": action=setclass(paid) 5.7.3.61 tagdl -- Download currently tagged files Displays a confirmation prompt and then begins downloading the set of files that the user has tagged. The form of the action is: action=tagdl 5.7.3.62 tagedit -- Edit the list of tagged files Display a list of the files that the user has tagged for downloading and allows the user to edit the list. The form of the action is: action=tagedit 5.7.3.63 telnet -- Invoke Telnet Internet program The telnet action invokes the Telnet program that is used to log onto remote computers through the Internet. The form of the action is action=telnet 5.7.3.64 top -- Return to top level menu The top menu action stops execution of the current menu and passes control to the top level menu. The effect is the same as if the current menu executed a 'return' action and all intermediate level menus also returned until the highest level menu was reached. 5.7.3.65 tpr -- Run TPL program The tpr action executes a TPL program. The form of the action is action=tpr(program [arguments]) where 'program' is the name of the program to be executed and 'arguments' are optional argument strings to pass to the program. Note that there is no comma between the program name and the optional argument strings. The program name and optional arguments should be specified just as you would if you were using the TPL system command to execute the program. For example, the following command runs a program named "cleanup": $item key=C action=tpr(\bbs\cleanup) The following example runs a program named "cleanold" and passes in the argument string "30": Chapter 5. Menu Compiler 60 $item key=O action=tpr(\bbs\cleanold 30) 5.7.3.66 tsxcmd -- Execute TSX command The tsxcmd action executes a TSX command or command file. The form of the action is action=tsxcmd(command[,list]) where "command" is the TSX command that is to be executed and "list" has one of the following values: 0 = Suppress all output generated by the execution of the command. The command is executed "silently". 1 = Allow output generated by the command to be listed to the screen. 2 = Allow output generated by the command to be listed to the screen and display a "-press a key to continue-" message when the command finishes. If you omit the 'list' argument, it defaults to 0. If you wish to execute a command file rather than a single command, begin the command with '@'. For example, the following action would delete all files in a work directory that have the extension ".TMP": $item key=D action=tsxcmd("del \work\*.tmp") The following action executes a command file named "\bbs\cleanup.cmd" and pauses at the end of the listing: $item key=L action=tsxcmd("\bbs\cleanup",2) 5.7.3.67 upload -- Upload a file The upload action uploads a file to the bulletin board system. The form of the action is action=upload(filename) where 'filename' is the specification for the file that is being uploaded. When the action is invoked, the user is prompted to begin the upload. This action is similar to the fdlupload action described in Section 5.7.3.21. The difference is that fdlupload is used to upload a file to the BBS files area and enter the file name and description into a FDL description file, whereas the upload action simply uploads a file but does not make it part of the BBS file system. For example, the following action uploads a file named "\data\daily.dat": action=upload(\data\daily.dat) Chapter 5. Menu Compiler 61 5.7.3.68 useroptions -- Change user options The useroptions action invokes the BBS operation that displays a list of user-changeable options such as password, chat handle, ANSI support, color, etc. and allows the user to change the options. The form of the action is action=useroptions 5.7.3.69 vote -- Enter voting system The vote action enters the BBS subsystem that is used to record and display user votes on issues the sysop sets up. See the SYSOP manual for information about defining voting issues. 5.8 $initial -- Initial action item The $initial menu item specifies actions to be performed automatically when the menu is first entered. The form of the $initial command is $initial action=keyword where 'keyword' is an action keyword. You may specify more than one $initial command in a menu. You may also use "if()" clauses to control which $initial items are to be executed based on conditional expressions. For example, the following $initial command sets the current activity description for the user to "Main menu": $initial action=actname(Main menu) Chapter 6 Logon and Callback Procedures TSX-BBS comes with standard user logon and callback procedures which are documented in this chapter. These procedures are written in the TPL programming language and the source files for these procedures are included in the files LOGON.TPL and CALLBACK.TPL. If you have purchased the TPL compiler, you can modify and recompile these procedures if they do not fit your needs. 6.1 Logon Procedure The TSX-BBS system is started by executing the command: BBSBIN:BBSRUN BBSBIN:LOGON This executes the BBSRUN.EXP program that is in the BBSBIN: directory and causes it to execute the LOGON.TPR TPL executable file. The logon procedure performs the following steps: 1. It checks for the existence of a BBS:WELCOME.MSG file. If such a file exists, it displays it as a logon greeting. This file could contain an ANSI display with your BBS name in block letters, etc. You may use substitution operators in the file such as described in Chapter 3. If there is no BBS:WELCOME.MSG file, TSX-BBS displays "Thanks for calling @bbsname@" where "@bbsname@" is replaced by the name of your bulletin board. 2. The user is then prompted to enter his first name, last name, and password. The first name and last name may be specified together on the first name line by separating them with either a space or a semicolon. 3. If the user name is recognized but the password is invalid, the user is given several chances to enter the right password. If this is unsuccessful, TSX-BBS logs the user off. 4. If the user name is not recognized, the user is given the choice of reentering the name or logging on as a new user. 5. If the user is logging on as a new user, TSX-BBS collects some basic information about the user including his address, phone numbers, number of lines per page, and color capability. The class for a new user is set to BASIC. You should use the SYSOP program to set the limits and privileges you want to grant to 62 Chapter 6. Logon and Callback Procedures 63 new users. See Section 15.2.4 on page 145 for additional information about user classes. 6. If callback verification has been enabled by the sysop, and the user has not yet been verified, then the callback procedure is invoked as describe in Section 6.2 starting on page 63. 7. If the user's account has an expiration date and the account has expired, the user's class is changed to EXPIRED which may reduce the user's privileges and limits. You should use the SYSOP program to set the limits and privileges you want to grant to expired users. See Section 15.2.4 for additional information about user classes. 8. A greeting message is displayed telling the user how much time he has available during the current session. 9. TSX-BBS checks for the existance of a file named BBS:DAILY.MSG. If the file exists and this is the first time that the user has logged on this day, the file is displayed. 10. TSX-BBS checks for the existence of files named BBS:NEWS1.MSG, BBS:NEWS2.MSG, BBS:NEWS3.MSG, BBS:NEWS4.MSG, and BBS:NEWS5.MSG. If any of these files exist, and the last modification date is more recent than the time when the user last logged on, the file is displayed to the user. 11. If the user's class is BASIC or VERIFIED and a file named BBS:REGISTER.MSG exists, the file is displayed. The sysop can place a message in this file encouraging users to subscribe to the bulletin board. 6.2 Callback Verification Many bulletin boards like to perform a callback verification procedure for new users. This procedure causes TSX-BBS to hangup and call the user's computer to verify that the user is actually located at the number that they provided during the registration procedure. There are two reasons for doing callback verification: 1. The procedure assures the sysop that he knows the real phone number that the user called from. This is useful in case the user engages in malicious actions and the sysop wants to locate the user. Frequently, the fact that users are aware that the sysop knows their real phone numbers is enough to deter improper actions. 2. TSX-BBS callback procedure stores the user's modem phone number in the user authorization record and will not allow another user to register the same phone number. This prevents the same user from registering multiple times with different names but the same modem phone number. This is especially important for systems that allow access without a paid registration. Chapter 6. Logon and Callback Procedures 64 If you wish to allow a second user to perform callback verification with the same phone number, you can use the SYSOP program to modify the first user's entry and remove the modem phone number. A second user will then be able to register using that number. When the callback verification procedure runs it performs the following steps: 1. Ask the user if he wants to do callback verification. If the user says "no", then verification is not done and the user's access class is left as BASIC. The user is given the opportunity to send a message to the sysop explaining why he did not do callback verification. 2. If the user has less than 5 minutes of available connect time, his time limit is increased to 5 minutes to allow time for the callback verification to be done. 3. If the user did not specify a modem phone number when he registered, the callback procedure asks the user to enter a modem phone number. 4. The CALLBACK.DAT file is used to clean up and validate the phone number. This procedure is described in Section 6.2.2. 5. A check is made to see if the number is registered to any other user. If so, the user is not allowed to use the number for verification. This prevents a user from registering more than once with different names. 6. A message is displayed telling the user that we are about to hang up and call him back. He is notified that he can type "ATA" to cause the modem to answer when he sees the "RING" message from the modem. 7. The phone is hung up and a delay is begun to give the modems on both ends a chance to reset. 8. TSX-BBS dials the number the user specified. If it is unable to establish a connection it hangs up, pauses, and tries once more. 9. If a connection is established, the user is asked to enter his password. If a correct password cannot be obtained, the user is logged off. Once a valid password is received, the user's authorization record is altered to indicate that callback verification has been successfully completed. The user's class is changed from BASIC to VERIFIED. 10. If the user's number is long distance, the verification hangs up and allows the user to call the system again. If the number is local, the callback does not hang up. Chapter 6. Logon and Callback Procedures 65 If you wish to use callback verification but do not want verification done for a particular user, use the SYSOP program to modify the user's authorization entry and set the "Called back" field to 'Y'. You should also change the user's class to VERIFIED or some other appropriate class. 6.2.1 Setting up Callback Verification There are a couple of steps that you must perform if you want to use callback verification. First, start the SYSOP program and type 'G' to select "General setup" from the main menu. Then position the cursor in the field next to the "Callback verification" label and type 'Y'. Press ESC twice to exit from SYSOP. 6.2.2 The CALLBACK.DAT File The second step of setting up the callback procedure is to create a control file with information about valid phone numbers. The name of the control file is BBS:CALLBACK.DAT. This is a simple ASCII file which you can create and modify using an ASCII editor. When the callback procedure runs, it begins by "cleaning up" the phone number that the user has entered. This procedure removes any characters that are not digits. For example, if the user entered "(615)327-3670", the clean up procedure would remove non-digits resulting in the number "6153273670". After cleaning up the number, the callback procedure reads the CALLBACK.DAT file and uses commands in the file to further clean up and validate the number. There are various types of commands in the CALLBACK.DAT file. Comment lines begin with either "//" or "!". Command lines begin with a keyword. The following commands may occur in the file: 6.2.2.1 STRIP command The STRIP command specifies phone number prefixes that are to be removed from the front of phone numbers. The form of the command is: STRIP prefix,prefix,... Where "prefix" is a digit string that is to be stripped from the front of the number. This is intended to deal with long distance numbers. Since the callback procedure prepends the appropriate characters needed to dial long distance numbers when that is necessary, it is desirable to strip digits such as '1' that the user may have specified at the front of a phone number. You should also strip off your own area code. If you specify multiple prefixes, separate them with commas. When the stripping is performed, the first prefix is compared with the start of the phone number. If a match occurs, the prefix is removed from the phone number and then the second prefix is compared with the remaining number. This procedure is repeated for each prefix you specify. You should specify "1" and "0" first and Chapter 6. Logon and Callback Procedures 66 then your local area code. For example, if your local area code is 615, an appropriate STRIP command would be: STRIP 1,0,615 Using this, the following phone numbers would all be converted to 555-1234: 615-555-1234, 1-615-555-1234, 1-555-1234. 6.2.2.2 DIAL Command The DIAL command specifies the modem command to dial a local number. The form of the DIAL command is: DIAL modem_command Where "modem_command" is the modem command string that is prepended to phone numbers when dialing local numbers. For most modems the appropriate command is: DIAL ATDT This causes the modem to use touch tone dialing. 6.2.2.3 LDDIAL Command The LDDIAL command specifies the modem command to dial a long distance number. The form of the LDDIAL command is: LDDIAL modem_command Where "modem_command" is the modem command string that is prepended to phone numbers when dialing long numbers. For most modems the appropriate command is: LDDIAL ATDT1 Note the "1" after "ATDT" that indicates the beginning of a long distance number. 6.2.2.4 LOCAL Command The LOCAL command specifies a pattern to identify local phone numbers. It should occur after the STRIP command. The form of the command is: LOCAL pattern Where "pattern" is a pattern string that is compared with the phone number after non-digits have been removed and the STRIP command has been performed. If the number matches the pattern it is considered to be a valid local number. The following characters can occur in the pattern: % -- Matches a single character. For example, "%%%%%%%" would match 3273670. Chapter 6. Logon and Callback Procedures 67 ? -- Matches a single character or a missing character. For example, "???????" would match 3273670 or 327 but would not match 6153273670. * -- Matches zero or more characters. (other characters) -- Other characters such as digits must exactly match characters in the corresponding character positions of the number. For example, the pattern "%%%3670" would match a number with any three digit prefix and the last four digits "3670". For U.S. local numbers the following LOCAL command would be appropriate: LOCAL %%%%%%% 6.2.2.5 LD Command The LD command specifies a pattern to identify valid long distance phone numbers. It should occur after the STRIP command. The form of the command is: LD pattern Where "pattern" is a pattern string that is compared with the phone number after non-digits have been removed and the STRIP command has been applied. The pattern has the same syntax as described for the LOCAL command in Section 6.2.2.4. For U.S. long distance numbers, the following command would be appropriate: LD %%%%%%%%%% If you do not want to do callback verification for long distance numbers you should omit the LD command from your CALLBACK.DAT file. In this case, the users will receive a message saying that TSX-BBS is unable to do callback verification and their usage class will remain as BASIC. 6.2.2.6 EXCLUDE Command The EXCLUDE command specifies phone numbers that are not valid for callback verification. The form of this command is: EXCLUDE number where "number" is a phone number to exclude. You may have more than one EXCLUDE command if you wish to exclude multiple numbers. It is suggested that you use the EXCLUDE command to keep the callback verification procedure from calling the police and fire numbers or other critical numbers that malicious users might enter for verification. The following is an example of a command that prevents callback verification from calling 555-1212: Chapter 6. Logon and Callback Procedures 68 EXCLUDE 555-1212 6.3 Logon Using a Drop File In some configurations, TSX-BBS may be run as a "server" on a satellite computer connected via serial lines with the primary BBS computer system. In this case, the primary BBS system may want to perform a logon on the TSX-BBS system for a user running on the primary BBS system to allow the user to access some function provided by TSX-BBS. Since the user has already logged onto the primary system, information about the user such as name, address, available connect time, and ANSI and color capability is known. It is advantageous for the primary system to be able to start TSX-BBS and automatically log on the user by passing the information about the user to TSX-BBS in a "drop" file. This operation can be done using the DROPIN.TPR procedure that is provided with TSX-BBS. The procedure is as follows: 1. The primary BBS system opens a communications line to the TSX-BBS system. 2. The primary system creates a drop file with information about the user. The form of the drop file is described below. The drop file can be created by running the COPY command on the TSX system and feeding in the lines to go in the file. A control-Z character can be sent to terminate the copy. The form of the command to copy data from the serial line to a file is: COPY TT: filename If multiple lines connect the two computers, the drop file should be given a unique name, or created in a unique directory, so that it will not conflict with the drop files for other users. 3. Once the drop file is created, the primary BBS should send TSX the command to start the BBS and run the DROPIN.TPR procedure. The name of the drop file can be specified as an argument. The following is an example TSX command to do this: RUN/LOCK BBSBIN:TPR BBSBIN:DROPIN BBS:TSXDROP.DAT where "TSXDROP.DAT" is the name of the drop file. You may specify whatever name you choose. If you do not specify the name of the drop file, BBS:TSXDROP.DAT is used by default. 6.3.1 Drop File Format The drop file is a simple ASCII file with carriage-return, line-feed delimited records. Each record passes an item of information about the user to be logged on. Each command begins with a command keyword and is followed by a space and an information string. The NAME command is required, the other Chapter 6. Logon and Callback Procedures 69 commands are optional. The following is a list of the valid commands: NAME first last -- Specifies the first and last name of the user. This command is required. TEMPUSER Y or N -- If "TEMPUSER Y" is specified, TSX-BBS deletes the entry for this user from the user authorization file when the user logs off. If TEMPUSER is not specified, TSX-BBS saves accounting information about the user. CLASS classname -- The TSX-BBS authorization class that is to be assigned to the user. The class names are defined using the SYSOP program. If no class name is specified, "BASIC" is used by default. TIME timeavail -- Specifies the number of minutes of connect time that the user has available. If this command is omitted, the daily time limit appropriate to the user's class is used. BAUDRATE value -- Specifies the baud rate at which the user is connected. This command does not cause TSX to change the actual baud rate, it merely informs TSX of the user's baud rate so that it can pass the value on to other programs in the DOOR.SYS drop file. The value is also used in download time estimations. ANSI Y or N -- Specify "ANSI Y" if the user's terminal has ANSI capability or "ANSI N" if it does not. If this command is omitted, TSX-BBS tests the user's terminal for ANSI capability. COLOR Y or N -- Specify "COLOR N" if the user cannot display color. IBMCHAR Y or N -- Specify "IBMCHAR N" if the user cannot display IBM graphic characters. LPP number -- Number of lines that user can display on a page. The default is 24. COMPANY company_name -- Name of company user is associated with. ADDR1 address -- First line of the user's street address. ADDR2 address -- Second line of the user's street address. CITY cityname -- City name for user's address. STATE statename -- State name for user's address. ZIP zipcode -- Zipcode for user's address. INETADDR address -- Internet address where user can be reached. VHPHONE phonenumber -- Voice home phone number. Chapter 6. Logon and Callback Procedures 70 DPHONE phonenumber -- Data (modem) phone number. WELCOME Y or N -- Specify 'Y' or 'N' depending on whether the normal welcome message should be displayed. The welcome message tells the user how much time is available during the current session and when they last logged on. They must press a key to continue after the welcome message. The default is to display the welcome message. NEWS Y or N -- Specify 'Y' or 'N' depending on whether new news files should be displayed. News files are only displayed if they exist and are more recent than the last logon date for the user. News files are named BBS:NEWSn.MSG. MAILCHECK Y or N -- Normally, TSX checks to see if a user has pending mail each time the user logs on. A message is printed if there is pending mail. If you wish to suppress this mail check you may use the "MAILCHECK N" command. MENU menuname -- Specifies the name of the main BBS menu that should be invoked for the user. The default menu is BBS:BBS. The following is an example drop file: NAME Phil Sherrod TIME 45 CLASS BASIC WELCOME N NEWS N MENU BBS:GAMES Chapter 7 File Library The file library is an important part of most bulletin boards and for some systems is the primary reason for their existence. TSX-BBS provides an outstanding file library as a a standard part of the system. Some of the features of this system are summarized below: . You can group your files in hierarchical categories. For example, you could have a category called "CD ROMs" and within that category have subcategories for "Swimsuit GIFs", "IBM Utilities", etc. . File entries can have multi-line descriptions. . The system maintains extended information about files such as the name of the person who uploaded the file, the download count, and the date of the last download. . A very powerful search command is provided that allows search expressions such as "windows and (clock or alarm)". . Users can tag files and then download all of the tagged files as a group. . You can use complex expressions to describe privileges users must have to download or upload files to each area. If a user has no access to a file category the existence of the category is not revealed. You can easily set up file categories that only members of certain groups can access. You can even set up privilege expressions that restrict access to file areas based on the day of the week or the hour of the day. . You can force all file uploads to go into a private area that the sysop can review before posting for public access. . You can write TPL programs to add files to file categories, list files in a category, modify file entries, and select files based on criterion such as date, size, download counts, etc. You can even write TPL programs that unzip files and then add them to the file library with the FILE_ID.DIZ file used for the description. 71 Chapter 7. File Library 72 7.1 File Categories and File Sets TSX-BBS allows you to group your files into three types of collections: file categories, file sets, and DOS directory lists. 7.1.1 File Sets A "file set" is a list of file descriptions. Typically, files with some common characteristic are grouped together in a file set. For example, you may want to create file sets for DOS utilities, Windows utilities, GIF files, etc. For each file in the file set TSX-BBS stores the following items of information: Description -- The description can be up to 18 lines long and each line can be up to 45 characters wide. DOS filename -- This is the actual name of the file as it is stored on disk. Display filename -- This is the name that is presented to the user when doing file browses. Usually this name is the same as the DOS file name but you have the option of specifying a different name. Date of file -- The creation date of the file. Date uploaded -- The date when the file was added to the file library. Size of file -- The size of the file. Uploaded by -- The name of the person who uploaded the file. Download count -- The number of times the file has been downloaded. Date last downloaded -- The date when the file was last downloaded. Free download -- Determines whether or not the download counts against the user's daily byte and time limits. Download cost -- Not presently used. Eventually this will allow the sysop to charge users for file downloads. The file entries for each file set are stored in a file whose name is designated by the sysop when the file set is created. The extensions for these files is normally ".FDL", which stands for File Description List. The FDL files should be stored in the directory to which the "BBS:" logical device name is assigned. For example, a file set for swimsuit GIFs might be named BBS:SWIM.FDL. Entries in FDL files are stored as binary "TIO" records. You cannot use an ASCII editor to modify FDL files. However, you do not need to directly edit the FDL files because the TSX-BBS SYSOP Chapter 7. File Library 73 program provides all of the tools you need to maintain file sets. You can write TPL programs to read, add, modify, and delete file entries. 7.1.2 File Categories A "file category" is a collection of one or more file sets. A file category may also include other file categories to produce a hierarchical structure. For example, you might create a file category called "CD ROMs" and within that category have categories for "Night Owl" and "Pier One". Within the "Night Owl" category you can have a file set for each group of files on the disk. When you create a category using the SYSOP program you are asked for the following items of information: Title -- The name of the category that is presented to your users. Filename -- The name of the file in which the list of file sets and subcategories is stored. The extension ".FAL" is added and the file is stored in the "BBS:" directory. Access priv -- This is a privilege expression of the form described in Chapter 4 that controls whether users can access file sets or subcategories of the category. If you leave this field blank, any user can access the category. If you specify a privilege expression and the value of the expression is false, then the user may not access any files within the category and the category does not appear in the file area display list for the user. Note that even if a user has the required privilege to access a category (or the category does not have a privilege expression), the user may be blocked by privilege expressions in lower level subcategories or at the file set level. The list of items within a file category is stored in a file whose name is designated by the sysop when the category is created. The file extension should be ".FAL" which stands for File Area List. The FAL files are stored in the directory to which the "BBS:" logical device name is assigned. The FAL files contain ASCII data and may be edited with an ASCII editor. However, it is rarely necessary to directly edit FAL files because the SYSOP program includes facilities for creating, modifying, and deleting file categories. There is a master FAL file named "BBS:MASTER.FAL" that is the "root" of the file library. You may not change the name of this file. All other categories are subcategories (or sub-sub..., etc.) of this master category. 7.1.3 Simple DOS Directories In addition to file sets and file categories, you may also include simple DOS directories as file areas. When a user selects a file area consisting of a simple DOS directory, he is presented with an alphabetical list of the files, their creation dates, and sizes, Chapter 7. File Library 74 much the same as doing a "DIR" system command. There is no FDL file to describe a DOS directory, so files do not have descriptions and information is not available regarding download counts, the person who uploaded the file, etc. The only advantage to using a simple DOS type directory is that there is no effort involved in maintaining the BBS file information. If a file is copied into the DOS directory it become available immediately to BBS users without any effort required to update FDL files. Similarly, all you have to do to remove a file is delete it from the directory. 7.2 Creating File Categories and File Sets The SYSOP program is used to create file categories and file sets. It is best to run the SYSOP program while you are reading this section so you can follow along with the instructions. When you start the SYSOP program you will be presented with a menu of management functions. Type 'F' to select "File library". You will then be presented with a list of all of the file sets and categories that are at the top level of the master category. You can use the up and down arrow keys and page-up and page-down to move through the list and highlight entries. If you highlight a file category entry, you can press Enter or right-arrow do move into the category and display a list of the file sets and sub-categories of the category. You can press left-arrow to move from within a category to the next higher level (i.e., closer to the root). 7.2.1 File category creation To create a new category, start the SYSOP program and select the file library option. If the new category is to be created at the top (root) level of the directory structure, type 'C' to select "Category create". If the category is a sub-category of some other category, highlight the category under which the new category is to be created and press Enter or right-arrow to enter that category. Continue this process if the new category is a sub-sub-category, etc. Once you reach the category where the new category is to be created, type 'C' to select "Category create". You will be presented with a menu prompting you to enter the title, the filename, and the access privileges for the category. The title is the name of the category that is presented to users in the file area list. The file name is the name of the file that holds information about items in the category. Enter from 1 to 8 characters for the name. "BBS:" will be prepended and ".FAL" will be appended. The "Access priv" field allows you to specify a conditional expression that controls which users can access this category. If you leave this field blank then there are no restrictions placed on Chapter 7. File Library 75 the category and any user can access it. If you wish to limit access, specify a conditional expression in the form described in Chapter 4. For example, if you wish to limit access to users with S5 privilege, specify "S5" as the access privilege expression. Once you have filled in the fields of the "New File Category" menu, press ESC to create the category or F4 to abort the creation. 7.2.2 File set creation To create a file set, return to the file library management menu and press 'F' to select "File set create". If the file set is part of some category other than the top level category, highlight the category that the file set goes in and press Enter or right-arrow to enter it. You will then be presented with a menu prompting you for the following items of information: Title -- Specify the name of the file set that you want to have displayed to your users. Filename -- Specify the name of the FAL file in which information about the file set is to be stored. You should specify a 1 to 8 character name, "BBS:" will be prepended to the name and ".FDL" will be appended. If you are setting up a simple DOS directory type area, do not specify a file name; just leave this field blank. Path -- Specify the device and directory where the files associated with this file set are stored. Note that since you may specify a device name, you may place different file sets on different devices. You are welcome to specify the name of a CD ROM drive if the files are located there. All of the files for a file set must be stored in a single directory on a single device. If you are setting up a simple DOS directory, specify the device and directory where the files are located. Access -- If used, this is a conditional expression that specifies what privilege is required to access files in the file set. See Chapter 4 for information regarding the form of this expression. If a user does not have access to a file set, the file set does not appear in the file area list displayed to the user. If you leave this field blank, any user can access any file in the file set. Download -- You may specify a conditional expression that controls who can download files from the file set. If you leave this field blank, any user can download any file from the area. Note: since the access privilege expression is separate from the download expression, you can allow users to browse through the file set but block them from downloading files. This could be useful for unregistered BBS users who you wish to allow to browse the board but not perform downloads. Chapter 7. File Library 76 Upload -- You may specify a conditional expression that controls who can upload files to the file set. If you leave the field blank, then any user can upload files to the file set. If you wish to disallow direct uploads to the file set, specify "NO" for the upload privilege expression. When a user uploads a file, the file immediately becomes accessible to other users (provided they have access privilege). Caution: it is usually not a good idea to allow ordinary users to upload files directly to public file sets. It is much better to create a special upload file set to which only the sysop has access. The sysop can then review files and move them to the appropriate file sets before other users can see them. To block all uploads to a file set you may specify "NO" as the conditional expression. Area # --- Free Download -- If this field is set to 'Y' then when a user downloads a file from the file set the download does not count against the daily time and byte limits for the user. Copy on download -- If this field is set to 'Y' then files in the file set are copied to a temporary directory before they are downloaded. This is essential for CD ROM changers because it will block other users if you hold a file open for long periods of time while a download is being done. When the download completes, the file is deleted from the temporary directory. CD ROM media -- Specify 'Y' if this file set is located on a CD ROM drive. Once you have finished filling in the menu, press ESC to create the file set or press F4 to abort the creation. If you wish to modify the attributes for a file set, use the arrow keys to highlight the line for the file set and press 'M' to select "Modify". When you create a new file set it will be initially empty. There are several ways that files can be added to a file set: they can be uploaded directly into the file set (if a user has the appropriate privilege), files can be moved from one file set to another, and you can add an entry to a file set using the SYSOP program. To "enter" a file set and list the files that are part of the file set, select the line for the file set and press Enter. When you do this you will see a two column list showing the names of the files and the first lines of the descriptions. To add a file to a file set type 'A' to select "Add". You will then be presented with a menu prompting you for the following items of information about the file: DOS filename -- Specify the actual name of the file as it is stored on disk. You may specify a device and directory name if the file is not in your current working directory; the file will be moved to the directory where files for the file set are stored. Chapter 7. File Library 77 Display filename -- This is the name of the file to be displayed to your users. If you leave this field blank, the DOS file name will be used. Download cost -- This value is not currently used. Uploaded by -- If you wish, you may enter the name of the person who uploaded the file. Free download -- Specify 'Y' for this field if downloads of this file are not to be counted against a user's daily time and byte limits. Note, you can also denote free downloads by specifying it as part of the file set attributes that apply to all files in the file set. Retain original copy -- As part of adding a file to a file set, the file will be copied into the directory where files that are part of this file set are stored. This directory is specified as one of the attributes of the file set. Normally, the original copy of the file is deleted after being copied to the file set directory. However, if you specify 'Y' for this field then the original copy of the file is not deleted after it is copied into the file set directory. Once you fill in the file entry menu, press ESC to complete the entry or press F4 to abort the entry. 7.3 Modifying File Descriptions and Attributes You can examine and modify file attributes and file descriptions. To do this, highlight the line for the file and type 'M' to select "Modify" if you wish to modify file attributes. Type 'E' if you wish to edit the file description. 7.4 Deleting Files, File Sets, and File Categories To delete a file from a file set, enter the SYSOP file library, go into the category and file set that has the file, and highlight the line for the file. Then type 'D' to select "Delete". A warning message will be presented, type 'Y' if you wish to proceed with the deletion. Note: this not only deletes the file entry from the file set FDL file, it also deletes the file from the disk. If you wish to save a copy of the file you must copy the file to a different name or directory before performing the delete operation in SYSOP. If you delete a file from the disk but do not use SYSOP to remove the entry from the file set, then the file will appear in file list displays but errors will occur if a user attempts to download the file. You can also use the SYSOP program to delete entire file sets or file categories. To do this, highlight the line for the file set or category and type 'D' for "Delete". A warning message will be Chapter 7. File Library 78 displayed telling you how many files will be deleted. Type 'Y' if you wish to proceed with the deletion. 7.5 Moving Files Between File Sets A common file maintenance operation is moving files from one file set to another. This will be especially useful if you configure the system so that all uploads go to a private file set that the sysop can review before moving them to the public file sets. The SYSOP program uses a "clipboard" concept to make it easy to move files. To move files from one file set to another, go into the SYSOP program and display the list of files in the source file set. Use the arrow keys or page-up/page-down to locate and highlight the line for a file to be moved. You can also type 'F' to select "Find" and type the first few characters of the name of the file you wish to located. Once you have highlighted the line for the file, type 'C' to select "Clipboard". Then type 'C' to select the "Cut into clipboard" action from the clipboard pulldown menu. The file entry will disappear from the primary file list and the name will be shown in a smaller "Clipboard" list in the lower right corner of the screen. You can then select additional files and cut them into the clipboard. Once you have collected a set of files in the clipboard, you are ready to move them to the destination file set. To do this, press ESC to exit from the file list for the source file set. Then highlight the line for the destination file set and type 'P' to select "Paste clipboard". The files will be added to the selected file set and their names will disappear from the Clipboard list. Not only are the file description entries moved to the new file set, the files themselves are moved from the directory for the source file set to the directory for the destination file set. If you move some files into the clipboard and then decide that you want to cancel the move and leave the files in the original source file set, reenter the source file set, type 'C' to select "Clipboard", and then type 'R' to select "Restore clipboard files". 7.6 Setting up Restricted File Areas Many bulletin boards have restricted file areas that can only be accessed by adults or other restricted classes of users. TSX-BBS has a very powerful facility for limiting file access. You can define privilege flags that mean "Adult", "Extended access", and other types of privileges. There are 80 privilege flags reserved for your use. You can also assign a "group" number to a user and use this group number to control which file areas a user can access. In addition, you can use privilege expressions to limit access to file areas based on the time of day or the day of the week. By combining these privilege tests you can create very complex access control expressions. Chapter 7. File Library 79 The key to devising and understanding access controls is "conditional expressions" which are described in Chapter 4 starting on page 31. If you have not yet read that chapter, you should do so now. We will explain how to set up restricted file sets by way of an example. Let's define an "Adult" privilege and create an "Adult" file set whose access is restricted to users with that privilege. The first step in defining a privilege is to start the SYSOP program and type 'U' to select "User authorization". Next type 'P' to select "Privileges" from the user authorization menu. You will be presented with the first of two pages showing the sysop defined privilege names. You can use page-up and page-down to move between the two pages. You will see that there are entries available for 80 privileges. Each privilege has a label of the form "Snn" where "nn" is a number in the range 00 to 79. Associated with the label is a field where you can type in a textual name. Let's make privilege S01 be the Adult privilege. Use the down arrow key to move the cursor to the field next to the S01 label and type "Adult" as the privilege name. Then type ESC to exit from the privilege name menu. You should now be positioned back at the primary user authorization menu with the list of currently authorized users displayed. If there are no authorized users type 'A' to add a user. If there are some authorized users, use the arrow keys to select one and press Enter to display information about the user. Next, press page-down twice and you should see a screen listing the privileges for the user. There are two columns of privileges. The left column shows the "Build-in Privileges" that are inherently known by TSX-BBS. The right column lists any "Sysop Defined Privileges". You should see "S1 Adult" as one of the entries. You can use the arrow keys to position the cursor to the Y/N field next to the privilege entry and type 'Y' or 'N' to enable or disable the privilege. After you have set the privilege appropriately, press ESC twice to return to the main SYSOP menu. The next thing to do is to define the Adult file set. From the main SYSOP menu type 'F' to select "File library". Next type 'F' to select "File set create". Enter "Adult" (or some other string) as the title for the forum, then enter "ADULT" as the file name. Also enter the path name where the files will be stored. The next step is to define the privileges required by users to access the file set. On the "Access" line enter "S1". This tells TSX-BBS to only allow users with S1 privilege to access this file set. Remember, we defined S1 to be the Adult privilege. Assuming you wish to allow any user who has access to the file set to be able to download from it, you can leave the "Download" line blank. You could specify a privilege expression if you wish to restrict downloads. Specify in the "Upload" line the privileges required to directly upload files to the file set. If you wish to allow any user with access to the file set to do direct uploads, leave the field blank. If you wish to disallow direct uploads, specify "NO" Chapter 7. File Library 80 in the field. Press ESC to exit from the "New File Set" menu once you have filled in the fields. That completes the creation of the restricted file set. Note that the conditional expression that you typed in the "Access" field was simply "S1". If you have need, you can use more complex expressions. For example, suppose you had two privileges with labels S1 and S2 and wished to allow users with either privilege to access the file set. In that case, the appropriate conditional expression would be "S1||S2". See Chapter 4 for a full explanation of conditional expressions. 7.7 Setting Up File Library Menus TSX-BBS comes with a FILE.MNU menu file that implements the file library functions. This menu file is stored in the directory to which the "BBSBIN:" logical device name is assigned. You are welcome to modify and customize this menu. You can also rearrange the functions so that they are accessed from other menus. See Chapter 5 for a full discussion of menu design. As described in Section 5.7.3, the "ACTION" phrases determine what actions will be taken when a menu key is pressed. The following is a list of the menu actions that relate to the file library. datesearch -- Search for files by date The datesearch action begins the BBS operation that searches a file area for all files created since a specified date. The user is prompted to enter the date. The form of the action is action=datesearch(falname[,fdlname]) where 'falname' is the name of the FAL file containing the area descriptions and 'fdlname' is the name of the FDL file that contains the file descriptions to be searched. If you omit the 'fdlname' argument then all FDL files listed in the FAL file are searched. For example, the following action searches files in a FDL list called "bbs:swim" that is part of a FAL area called "bbs:master": action=datesearch(bbs:master,bbs:swim) whereas the following action searches all FDL files contained in the bbs:master FAL: action=datesearch(bbs:master) fallist -- Display file area list The fallist action displays a list of file areas. The form of the action is action=fallist(falname,heading) Chapter 7. File Library 81 where 'falname' is the name of the FAL file containing the area descriptions and 'heading' is a string to be displayed at the top of the selection list. For example, the following action displays a list of files described by the "bbs:master.fal" file and prints "All file areas" as the title: action=fallist(bbs:master,"All file areas") falsearch -- Search file descriptions The falsearch action invokes the BBS subsystem that searches file descriptions for a text string that the user enters. This action performs "global" searches that span multiple file sets. The form of this action is action=falsearch(falname,heading) where 'falname' is the name of the FAL file containing the list of files (and/or subareas) that are to be searched, and 'heading' is a string to be displayed during the search. For example, the following action searches all files defined by the bbs:master.fal fal file and displays "All file areas" as the search heading: action=falsearch(bbs:master,"All file areas") See Section 7.8 for information about the types of expressions that users can specify for searching. fdllist -- List files in an FDL The fdllist action causes the BBS to list the descriptions of the files in a specified file set (FDL) that is part of a specified file category (FAL). The specified FAL file must have an entry for the specified FDL file. As the names are listed the user is provided options such as tagging, downloading, searching, etc. The form of the action is action=fdllist(falname,fdlname) where 'falname' is the name of the FAL file and 'fdlname' is the name of the FDL file. For example, the following action lists all files in the bbs:swim.fdl file that is part of the bbs:master.fal area: action=fdllist(bbs:master,bbs:swim) fdlsearch -- Search through file list The fdlsearch action prompts the user to enter a word or phrase to search for and then searches through the file descriptions in a specified FDL file that is part of a specified FAL area. Files that have the matching word or phrase in their names or descriptions are listed and the user may tag and/or download them. The form of the action is Chapter 7. File Library 82 action=fdlsearch(falname,fdlname) where 'falname' is the name of the FAL file area file and 'fdlname' is the name of the file description file. This action differs from the falsearch action in that falsearch searches all file descriptions that are in all file sets and subcategories of a specified category, whereas fdlsearch searches only a specified file set. fdlupload -- Upload a file The fdlupload action begins a sequence that prompts the user for a file name and description and then uploads the file to the bulletin board and enters the description into a specified FDL file. The form of the action is action=fdlupload(falname,fdlname) where 'falname' is the name of a File Area List (FAL) file that includes the FDL file, and 'fdlname' is the name of a File Description List (FDL) file into which the description for the file being uploaded is stored. For example, the following action begins an upload. The file description is placed in a file named "bbs:newfiles.fdl". The File Area List (FAL) is "bbs:master.fal". action=fdlupload(bbs:master,bbs:newfiles) tagdl -- Download currently tagged files. The form of the action is: action=tagdl tagedit -- Edit the list of tagged files. The form of the action is: action=tagedit 7.8 Search expressions TSX-BBS offers a very powerful file search facility -- more powerful than you probably have encountered in other BBS systems. In addition to searching for an individual word, you can also search for logical expressions involving words combined with AND, OR, and NOT operations. You can use parentheses to group terms in the expression. The AND operator selects only those files whose descriptions have the words (or subexpressions) joined by AND. For example, if you want to find a clock program for Windows, try the following search string: clock and windows Chapter 7. File Library 83 The OR operator selects files whose descriptions contain either of the specified words (or subexpressions). Perhaps you would like to find files related to amateur radio; try the following search expression: amateur or radio or ham The NOT operation excludes any file containing the specified word. For example, suppose you want to find amateur radio files but are not interested in Windows related files; you might try this search string: (amateur or radio or ham) and not windows How about GIF files related to Sharon Stone who starred in Basic Instinct: gif and ((sharon and stone) or (basic and instinct)) When performing the comparison, the search matches each word you specify with words in the file name and description. A match will occur if one of your words matches the front part of a word in a file description but a match will not occur if one of your target words is embedded in another word. For example, a search for "sin" would match with "sin", and "single" but would not match with "insincere". Similarly, a search for "book" would match with "book", "books", and "booking" but not "handbook". 7.9 PCBoard DIR File to FDL File Converter TSX-BBS comes with a program for converting PCBoard style file description files to TSX-BBS FDL files. The name of this program is PCBTOFDL. This program is useful not only for sites that are converting to TSX-BBS from PCBoard, but also for use in converting file descriptions that are distributed on CD ROMs in PCBoard format. The command to perform a conversion is: PCBTOFDL pcb_file fdl_file where "pcb_file" is the name of the PCBoard style description file and "fdl_file" is the name of the TSX-BBS FDL file to be created. The default extension for the "pcb_file" is ".DIR"; the default extension for the "fdl_file" is ".FDL". This program creates a FDL file with the specified name. You must edit the MASTER.FAL file and make an entry for the FDL file. Chapter 7. File Library 84 7.10 TBBS DIR File to FDL File Converter A program named DIRTOFDL is provided with TSX-BBS to convert TBBS description files to TSX-BBS FDL files. The command to perform a conversion is: DIRTOFDL dir_file fdl_file file_directory where "dir_file" is the name of the TBBS DIR file to be converted, "fdl_file" is the name of the TSX-BBS FDL file to be created, and "file_directory" is the device and directory where the files described by the DIR file are stored. This program creates a FDL file with the specified name. You must edit the MASTER.FAL file and make an entry for the FDL file. Chapter 8 Personal File Workspace In addition to the file libraries described in Chapter 7, TSX-BBS also allows each user to have a "Personal File Workspace". A personal file workspace is a private file storage area for each user. Unlike the TSX-BBS file libraries, personal file workspaces do not have extended file descriptions; each file has a simple 1 to 8 character file name and 1 to 3 character extension (i.e., it is a standard DOS file name). There are two primary uses for personal file workspaces: 1. Personal file workspaces are used as transient areas to hold files being uploaded and downloaded to the Internet using the FTP program. Since the FTP program always transfers files between the Internet and a local file area on the computer where FTP is running, it is necessary to use the personal file workspace as a temporary storage area to which a user can upload and download using X/Y/Z-modem before running FTP to send a file or after running FTP to receive a file. The use of personal file workspaces with FTP is described in Chapter 12. 2. Groups of users can use a shared workspace for exchanging files. For example, suppose your BBS is supporting a ham radio club that wishes to allow users to upload and exchange files among members of the club. You could do this by setting up a file library with access restricted to members of the club, but the club members would have to enter file descriptions when files were uploaded. By assigning all members of the club a common personal file workspace, you can provide them with a convenient, common file area that they can upload to and download from without having to enter file descriptions. Users are allowed to delete files from their personal file workspaces. 8.1 Temporary and Permanent Workspaces The sysop can limit the use of personal file workspaces. For each BBS user the sysop can authorize the following uses of a personal file workspace: None -- The user is not authorized to use a personal file workspace at all. Note: if a user is authorized to use FTP but is not authorized to use a personal file workspace, TSX-BBS overrides 85 Chapter 8. Personal File Workspace 86 the workspace setting and allows the use of a temporary workspace. Temporary -- The user is allowed to use a personal file workspace, but all of the files in the workspace, as well as the workspace directory itself, are deleted when the user logs off of the BBS. This is a reasonable setting to use if you are just providing the workspace as a transient area for files being transferred with FTP. Users wishing to send a file can use X/Y/Z-modem to upload the file to the personal file workspace and then use FTP to send it through the Internet. After the file is sent there is no need to continue to store it in the personal file workspace. Similarly, when receiving a file with FTP, the file is transferred to the personal file workspace and then X/Y/Z-modem is used to download the file to the user's computer. Once the file has been downloaded, it is no longer necessary to continue storing it in the personal file workspace. Permanent -- The user is allowed to store files in a personal file workspace and the files are not deleted when the user logs off. This setting is nice in that users can receive files through the Internet with FTP, log off, then log on later and use X/Y/Z-modem to download them to their personal computers. This setting also prevents files from being deleted if the user is inadvertently disconnected during a BBS session. However, unless you are careful, you may end up tying up a lot of your disk space storing files for your users. A permanent workspace is appropriate for the situation where your BBS is providing common storage for a group of users who wish to exchange files. The type of workspace a user is authorized to use is specified using the SYSOP program. Each user's authorization entry has a field named "Personal file workspace". When you select this field and press "Enter" a pulldown menu will appear with three options: "None", "Temporary", and "Permanent". Highlight one of the options and press Enter to select it. You can also assign workspace types and size limits using the user authorization class facility. Each class has an associated workspace type and size limit. 8.2 Workspace Size Limits The sysop can limit the amount of file space available in each user's personal file workspace. This limit applies to both temporary and permanent workspaces. An abort will occur if a user attempts to upload more files to his personal file workspace than the limit. An abort will also occur if an attempt is made to use FTP to receive more files than will fit in the personal file workspace. The user can delete files from his personal file workspace once they are no longer needed in order to free up space for more files. The workspace size limit is specified as part of the user authorization section of the SYSOP program. Each user can have a Chapter 8. Personal File Workspace 87 different limit. The value is specified in the field named "Personal workspace size" that is part of each user's authorization entry. If you specify a value of 0 for this field (or leave it blank) no limit is placed on the amount of file space that the user may use. You may also specify workspace size limits as part of a user authorization class. 8.3 Workspace Directories The sysop can assign a device and directory for a user's personal workspace or the sysop can allow TSX-BBS to create a directory name based on the user's BBS identification number. If the sysop designates a particular directory, the workspace is treated as a permanent workspace, and the files are not deleted when the user logs off. This overrides the "Temporary" workspace setting. If you wish to have several users share the same workspace you must specify the same directory name for each user's workspace directory. If you wish to designate a particular device and directory for a user's workspace, specify the directory in the field named "Personal workspace directory" that is part of each user's authorization entry. If you leave this field blank, a workspace directory is created for the user. The user's BBS identification number (which is unique to each user) is used to create the directory name. These workspace directories are created under the directory whose name is specified in the "Temp directory" field that is part of the "General Setup" screen in the SYSOP program. 8.4 Personal Workspace Management Users may list the files in their personal workspace, upload files to it, download files from it, and delete files from their workspace. The menu action code to invoke the personal workspace browse function is "pws". An example of a menu entry to invoke the personal workspace management when the user types 'P' is $item key=P action=pws Within menus and display files, you can use conditional expressions to determine if a user is authorized to use a personal workspace. Within a logical expression, the string "pws" has the value 0 (false) if the user is not authorized to use a personal workspace. It has the value 1 if the user is authorized for a temporary workspace and it has the value 2 if the user is authorized for a permanent workspace. For example, the following is a fragment of a menu file that presents the personal workspace option only to those users who are authorized to use personal workspaces (either temporary or permanent): Chapter 8. Personal File Workspace 88 @if(pws)@@eol@ `Personal workspace @endif@@eol@ $item key=P action=pws if(pws) The following logical expression would be true only for those users who are authorized to use permanent workspaces: "pws==2". The following substitution operators may be used within display files to insert information about the user's personal workspace: @pws@ -- Inserts a string indicating what type of personal file workspace the user is authorized to use. One of the following strings will be inserted: "None", "Temporary", "Permanent". @pwsavail@ -- Inserts the remaining number of bytes available in the user's personal file workspace. @pwsdir@ -- Inserts the name of the user's personal workspace directory if a permanent directory has been assigned. Inserts nothing if the user does not have a permanent workspace directory. @pwssize@ -- Inserts the total number of bytes that may be stored in the user's personal file workspace. "(unlimited)" is stored if there is no limit. Chapter 9 Discussion Forums and Newsgroups 9.1 Introduction TSX-BBS includes a powerful message storage and retrieval system that is ideal for Usenet newsgroups, Fido echoes and other types of discussion forums. The message system can efficiently store and recall messages from thousands of message areas making it ideal for major Usenet storage sites. The maximum number of messages and message areas is limited only by available disk space. Message text compression is performed automatically to reduce disk space requirements. Message categories are organized in a hierarchical (tree-structured) fashion. The top level can have categories such as Usenet and Fido. Within the Usenet group there might be subcategories such as "alt" and "comp". Within "usenet.alt" you would find additional subsubcategories, etc. Users can explore the areas by moving up and down through the hierarchical levels or by browsing the full set of forums as an alphabetical list. By using sophisticated indexing techniques, TSX-BBS is able to provide virtually instantaneous access to any message area. Users can locate message areas by doing searches for words in the area name. Users also can search for messages containing specified words and expressions in the body of the message. Within an area, messages are sorted by their creation date (rather than the date they were received by the board). Messages on the same topic are grouped into "threads" making it easy to follow an exchange of messages. TSX-BBS keeps track of the last message read in each area so that users can easily read new messages in forums with many messages. Reading messages in one area does not affect the last-message-read pointer for other areas. A "privilege expression" (see Chapter 4) can be associated with each area to control which users can access the area. This makes it easy to set up adult discussion forums and to create private forums for groups that are using the board as a message exchange system. Forum access restrictions are especially useful for Usenet which has a number of newsgroups which are not suitable for general distribution. A QWK facility is built into TSX-BBS to provide efficient downloading of messages for off-line readers. 89 Chapter 9. Discussion Forums and Newsgroups 90 Users can interactively add new messages to forums or add messages through QWK processing. Users can reply to messages in a forum written by someone else. Depending on the forums and certain options, new messages and replies may be broadcast to external networks. Two common examples are Usenet and Fidonet messages. When a message is posted in a forum and the recipient of the message is a user on the local BBS, a notification message is sent to the user through E-mail. Users have the option of disabling E-mail notification messages in the "User configuration" menu. Forum messages may be posted by users of your BBS using the interactive message editor built into TSX-BBS as well as QWK uploads. Forum messages can also be received from other systems through networks such as Fidonet and Usenet. Forum messages received from other systems may come in through dial-up connections, satellite receivers, and high-speed network connections such as Ethernet. A "tosser" program is used to process messages received from other sites and post the messages on your discussion forum. Tosser programs can run while your BBS is in full operation with users browsing message areas. In addition to automated message addition through tossers, there is automated message deletion through a program called the sweeper. It will expire messages based on several criteria including how old the message is and how many messages are in the area. The sweeper can be run while users are on the BBS and it can even run at the same time that the tossers are run. The sysop specifies the locations of the forum control and data files though the SYSOP program. To allow for very large forum databases, forum control and data files may be split across disks or networked systems. TSX-BBS allows up to 64535 forums to be defined. 9.2 Batch Addition and Deletion of Messages Forum messages may be posted by users of your BBS using the interactive message editor built into TSX-BBS as well as QWK uploads. Forum messages can also be received from other systems through networks such as Fidonet and Usenet. Forum messages received from other systems may come in through dial-up connections, satellite receivers, and high-speed network connections such as Ethernet. A "tosser" program is used to process messages received from other sites and post the messages on your discussion forum. Since the message files received through different connection types (satellite, dial-up, etc.) tend to be in slightly different formats, a different tosser is required for each style of message file. After a received message packet file has been processed and the messages added to your forums, the packet file may be deleted. The tossers may process many files, each of which may have many messages. When the tosser encounters a message for a forum which does not yet exist it can create the forum automatically and report Chapter 9. Discussion Forums and Newsgroups 91 the creation to the sysop. Tossing under TSX-BBS is very fast and is very efficient. 9.3 How to expire messages in forums. After some period of time it will be necessary to delete messages in forums since disk space is limited. The sweeper program FSWEEP.EXP actually does the message deletion. Its operation will be described in Section 9.4. This section gives an overview of the processing and describes how the SYSOP program can be used to specify the required parameters. There are three main things which control message deletion in a forum: the age of the message in days, the minimum number of messages to keep in a forum, and the maximum number of messages to allow in a forum. In order for messages to be deleted some or all of the three parameters must be specified. One of the following combinations must be specified. 1. max number of messages. 2. max number of days. 3. max number of messages and max number of days. 4. max number of messages and max number of days and min number of messages. 5. max number of days and min number of messages. Note that it is nonsensical to specify a minimum number of days without also specifying the maximum number of days. Consider that if only the max number of days and the min number of days were specified then messages would be deleted until only the max number remained. Since this must be greater than the min number of days it was not used in deciding to delete messages. The sweeper must be told what these parameters are for each forum that it processes or no messages will be deleted. It does this through command line parameters or by collecting information which is associated with the forum. The command line parameters are specified when the program is run and are described in Section 9.4.1. Each forum or hierarchy of forums can be assigned unique values for these parameters with the SYSOP program. These values are specified during forum creation or modification in the appropriate screens. Section 15.10.3 describes forum creation. Section 15.10.4 describes forum modification. Like forum privileges, the values for these parameters are inherited and can be overridden. For example, if the name component "usenet.alt" were given the number of days to expire as 7 Chapter 9. Discussion Forums and Newsgroups 92 then all of the forums under "usenet.alt" would have an expiration of 7 days. If the name "usenet.alt.cooking" were then given the number of days to expire as 14 this would override the value of 7. All forums under "usenet.alt.cooking" would then have 14 days as the number of days to expire. If the forum "usenet.alt.cooking.chili" were given a value of 21 as the number of days to expire then this would override the 14 days from "usenet.alt.cooking". This scheme allows complete flexibility for specifying expiration parameters. It also allows values specified in one place to affect potentially thousands of forums but also allows for individual tailoring for specific cases. This makes for ease of maintenance. If all the forum's expiration parameters are specified in this way then the sweeper program can simply be scheduled to run periodically without having to specify any unique parameters. This can result in more automatic processing of forum sweeping and less system management 9.4 Expiring messages; The Sweeper program FSWEEP Once messages are in the forums they remain there until they expire. It is the job of the program called FSWEEP to delete expired messages from the forum message files. The sweeper can be run at any time, even while users are active in the forums being swept. Typically, the forum sweeper is scheduled to run at night when the general BBS load is light. Its basic function is to delete expired messages from forums. In addition, it can: . Restrict a forum to a certain number of messages. . Ensure that a certain minimum number of messages are retained. . Initialize a forum, which deletes all messages and resets the next available message to 1. . Only sweep forums which have been modified since the last sweep. . Sweep a single forum specified via name or number. . Sweep a group of forums which have a common name prefix. This is useful for sweeping specific grand divisions. . Expire messages based on when they were written or when they were added to the forum. When tossers and the sweeper work in conjunction the sweeper will only attempt to process forums which were specifically added to by a tosser. Since not all forums are generally added to between sweeper runs this can greatly increase the efficiency of the Chapter 9. Discussion Forums and Newsgroups 93 sweeper. Like tossing, sweeping out old messages is also very fast under TSX-BBS. 9.4.1 Sweeper command options The sweeper can be told what to do through command line switches. Each switch governs some aspect of the operation. The switches are specified here. More than one switch can be specified, although not all combination are legal. Illegal combinations are flagged when the program starts. As mentioned, the number of days, the minimum number of messages and the maximum number of messages can be specified for a forum or group of forums through the SYSOP program. The values for min, max, and number of days must be specified either through the command options described here or through the SYSOP program. If there are no values specified the sweeper will not delete any messages. This can be a useful way to have permanent forums. Values for the min number of messages, max number of messages, and max number of days can be specified either through the command line options or the options derived from the forums through specification of the SYSOP program, or both. In other words, the value for the number of days can be specified on the command line while the maximum number of messages can be derived from the forum. The values from the command line are overridden by the values from the forum, so if a max number of days is specified on the command line and it is defined with the forum the value from the forum will take precedence. . /MINI (default) This tells the sweeper to perform a 'mini' sweep. The sweeper will only process forums which have had messages added since the last sweep. This is the default. The only down side to using /MINI is that it is possible for a forum which has not had any new messages added to eventually contain messages which are all expired and which should be deleted. The way to deal with this is to periodically (say, once a month) perform a full sweep. An example of how this might be done automatically is demonstrated in the BBS:FSWEEP.CMD command procedure. . /FULL This tells the sweeper to process all forums, not just ones which have had new messages added since the last sweep. . /CLUSTEROPT (default) This tells the sweeper to not bother sweeping a forum if the size of the data file falls beneath the size of a cluster. The reason is that if the data file is less than a cluster in size no disk space would be reclaimed for other messages by sweeping. Bypassing the forum saves time during the sweep. Chapter 9. Discussion Forums and Newsgroups 94 This actually allows the forum to have a few more messages in it with no additional overhead. . /NOCLUSTEROPT This switch is specified if the sysop wants to more precisely control the messages without regard to disk space reclamation. A forum will always be processed. . /NUMBER=n This switch is used to instruct the sweeper to process a specific forum whose number is specified. The value 'n' is the forum number. An example invocation is RUN BBSBIN:FSWEEP/NUMBER=1234 . /NAME=name This switch is used to instruct the sweeper to process a specific forum whose name is specified. The value 'name' is the forum name. An example invocation is RUN BBSBIN:FSWEEP/NAME=usenet.alt.cooking.chili . /DAYS=n (default=7) This tells the sweeper how many days to allow messages to remain in the forum before expiration. The value 'n' is the number of days. An example invocation is RUN BBSBIN:FSWEEP/DAYS=10 . /MAXMSGS=n (default = no maximum) This tells the sweeper to restrict the number of messages in the forum to the specified maximum. "nnn" is the maximum number. After all the expired messages are deleted the sweeper will delete enough of the older messages to reduce the number of messages to below this parameter. An example invocation is RUN BBSBIN:FSWEEP/MAXMSGS=250 . /INIT This tells the sweeper to delete all messages from the forum and reset the next available message count to 1. . /MINMSGS=n (default=no minimum) This tells the sweeper to ensure that there are at least a specified minimum number of messages left in the forum. Even if a set of messages are expired it is sometimes useful to leave them around so that browsing users can see the kind of messages available in a forum. If deleting expired messages Chapter 9. Discussion Forums and Newsgroups 95 would reduce the count of messages below the specified minimum they will be left in the forum. . /WRDATE This switch tells the sweeper to expire messages by the date they were written, not the date they were posted. It is quite common for messages to be one or more days old by the time they are added to the forum. . /HELP This will print out some help on the sweeper and exit. . /VERBOSE This is a debugging option which prints all messages directed to log files to the terminal. . /BASENAME=name This switch is used to tell the sweeper to restrict sweeping operations to a set of forums which begin with a common name. This can be used to restrict a sweep to certain grand divisions, for instance, or certain forums under any name. This may be necessary due to a very large volume of messages, for instance, or to implement special limits for a set of names. Here are several examples which each sweep a different section. In this example we see that it is possible to specify different expiration limits for different areas. RUN BBSBIN:FSWEEP/DAYS=10/BASENAME=fido RUN BBSBIN:FSWEEP/DAYS=14/BASENAME=local.discuss RUN BBSBIN:FSWEEP/DAYS=2/BASENAME=usenet.comp.ibm In general, one switch which selects the forum or forums for processing can be combined with switches which establish the criteria for message deletion. The switches /NAME, /NUMBER, /BASENAME, /FULL, and /MINI select the forums for processing. Each is a subsetting option which restricts the scope of the sweep. Normally only one is specified. The exception is that /BASENAME can be specified with /FULL or /MINI. It may be desirable to limit a sweep of forums under a base name to only those modified. The switches which establish the criteria for message deletion are either /INIT or some combination of /MAXMSGS, /MINMSGS, /WRDATE, /DAYS, and /CLUSTEROPT. The /INIT switch cannot be combined with any of /MAXMSGS, /MINMSGS, /WRDATE, /DAYS, and /CLUSTEROPT. You can specify any of /MAXMSGS, /MINMSGS, /WRDATE, /DAYS, or /CLUSTEROPT together, except that if /MINMSGS and /MAXMSGS are both specified /MINMSGS must be less than /MAXMSGS. Chapter 9. Discussion Forums and Newsgroups 96 9.4.2 Examples This example demonstrates the default. It performs a mini sweep and expires messages after 7 days. Cluster optimization is performed. ! ! These two commands are equivalent ! RUN BBSBIN:FSWEEP RUN BBSBIN:FSWEEP/DAYS=7/CLUSTEROPT/MINI This example sweeps only the forums underneath "usenet.alt.cars" and deletes messages over 10 days old. Only forums which have been modified since the last sweep will be selected for sweeping. RUN BBSBIN:FSWEEP/BASENAME=usenet.alt.cars/DAYS=10 This example sweeps only the forums underneath "usenet.alt.cars" and deletes messages over 10 days old. All forums will be swept, regardless of whether or not they have had messages added to them. RUN BBSBIN:FSWEEP/BASENAME=usenet.alt.cars/FULL/DAYS=10 This example sweeps all forums restricting the number of messages to 40. RUN BBSBIN:FSWEEP/FULL/MAXMSGS=40 This example initializes forum number 1237. All messages are deleted and the next available message number is reset to 1. RUN BBSBIN:FSWEEP/INIT/NUMBER=1237 This example performs a sweep on the forum "usenet.alt.chili" and expires messages over 4 days old. It also specifies that there should be a minimum of 10 messages kept. This may means that some expired messages will be retained in order to keep the minimum requested. RUN BBSBIN:FSWEEP/NAME=usenet.alt.chili/DAYS=4/MINMSGS=10 9.4.3 Scheduling the sweeper The sweeper is scheduled through the scheduling utility in SYSOP. The command procedure FSWEEP.CMD invokes the sweeper. This command procedure contains the command with options to invoke the sweeper. The scheduling utility is described in Chapter 20. 9.5 Forum Identification and Naming Conventions Each forum has a unique identifying number and a name. The forum number is in the range 1000 to 65535, inclusive. The forum name is the name of the topic of the forum. The names follow the usenet Chapter 9. Discussion Forums and Newsgroups 97 newsgroup naming convention of name pieces separated by periods. An example might be "alt.cooking.chili". There is an actual limit of 19 name pieces and a limit of 40 characters per name piece. Most forum names are rarely longer than 30 bytes and generally have 4 or 5 name pieces at most. Names may not contain spaces but there are few restrictions aside from that. Letters, numbers, and most punctuation characters are allowed. Each forum has one control and one data file that contain the forum data. The location of these two files is specified through the SYSOP program. TSX-BBS was designed to handle efficiently thousands of forums each with potentially dozens or hundreds of messages. In addition to forums which mirror Usenet newsgroups, TSX-BBS supports the addition of message bases from Fidonet echoes. There are many other types of networks which have discussion areas and the TSX-BBS forum processing is designed to include them. You can also have local forums for topic such as classified ads, local politics, around-town discussions, etc. Local forums allow your BBS users to exchange messages but the messages are not sent to any other sites. The word hierarchy is defined as "Any system of persons or things ranked one above another". There is a hierarchical naming convention in TSX-BBS forums. If you have had experience with the DOS file system then you have already had experience with a hierarchical naming convention. As you are probably aware, in the DOS file system there is a concept of directories which can contain files or other directories. The topmost directory is called the root directory. If the directory structure was diagramed, it would resemble a tree. The same file name can exist in more than one directory. To uniquely identify a file you must specify not only the file name but also the directory path in which the name occurs. All of this should be quite familiar to any DOS or Unix user. The TSX-BBS forum naming convention is very similar to the DOS file system naming conventions. Here is a list of similarities. . Instead of directories and file names there are "name components". . Instead of names separated by '\', forum name components are separated by a single period ('.'). . An example DOS file name is "\LIST\NEB\WAT.LOG". An example TSX-BBS forum name is "usenet.alt.cooking.chili". . In DOS, the lowest level name is a file. In TSX-BBS the lowest level name component represents a forum which contains messages. Chapter 9. Discussion Forums and Newsgroups 98 . In DOS, a directory can contain many other directories or files. In TSX-BBS, a particular name component can contain other name components or forums. Thus under the name "usenet.alt.cooking" there could be names "tex-mex", "chinese", "italian.northern", "italian.southern", and many others. Each would have the prefix "usenet.alt.cooking". . A name component may refer to a forum which actually contains messages or it may not. The analogy with the DOS file structure is that a name such as "\HELP\SUBJ1\UPDATE" may be a file or it may be another directory. . DOS has the concept of the root directory. In TSX-BBS there is no root name per se, but the top level name is called the grand division. . Both the SYSOP and users can browse the forum name hierarchy just as one would peruse the DOS file system. The displays for both the SYSOP and users will display a list of names at the current level and have options for going "up" and "down". In DOS, the DIR command displays the names at the current level and the CD command allows you to go up or down the directory hierarchy. Unlike DOS, both the SYSOP and the user displays will display all the forum names alphabetically. . Unlike DOS, a name component can contain both a forum and refer to other name components. Under DOS, a name is either a directory or a file, but not both. Thus, there could be a forum called "usenet.alt.cooking.italian" which contains messages and forums called "usenet.alt.cooking.italian.northern" and "usenet.alt.cooking.italian.southern" which each contain messages. Each forum has a unique number between 1000 and 64535. Each forum is defined by two files, a control file and a data file. The names of the files are "Fn.CTL" and "Fn.DAT", where 'n' is the forum number. Names which are not forums do not have control files. Forum control and data files are located in subdirectories beneath "BBS:\FORDATA\", by default. The SYSOP program can be used to tailor the location of the control files based on the forum numbers. This allows the sysop to break up areas across disks when there are many large forums. The SYSOP program is used to create, delete, and modify forums. The control file BBS:FTREE.DAT contains the forum definitions used by the SYSOP program. Section 15.10.3 describes forum creation. Section 15.10.5 describes forum deletion. Section 15.10.4 describes forum modification. In TSX-BBS there is a convention that the topmost name is reserved for the type of network to which a set of forums belong. This topmost name is called the "Grand Division". For Usenet newsgroups Chapter 9. Discussion Forums and Newsgroups 99 this name is "usenet". For Fidonet echoes this name is "fido". As other networks are incorporated more names will be assigned. The grand division name is mainly used by tossers. Tossers are programs which break up container files and add messages to forums automatically. The grand division name enables tossers to add thier messages to the appropriate set of forums. For forums which are locally defined and which contain only local messages the grand division name "local" is recommended. 9.6 Forum Access Privileges By default, users can read and write messages in all forums and can delete messages which they had previously posted. If the user has SYSOP privilege they can delete messages in any forum. Using the SYSOP program, the sysop can erase all messages in a forum. This basic functionality will probably suffice for most BBS's so understanding this section is not required for basic forum operation. For various reasons it may be desirable to restrict access to certain forums to certain users or to certain classes of users. Each forum may have three kinds of privileges associated with it: the privilege to even be aware of it (read privilege), the privilege to post to it (write privilege), and the privilege to delete any message from the forum (control privilege). When the user lacks read privilege for a forum he is unaware of its existence; the name does not appear on any of the forum menus or on the list of forums the user may download. Once privileges are associated with forums the users trying to access the forums must have the privileges specified for the operations they are trying to perform. For a general discussion of privileges and privilege strings, see Section 4, page 31. A basic understanding of privileges and privilege strings is necessary in order to understand how to use privileges with forums. Privilege strings are used to describe privileges. The SYSOP program is used to define these privileges in a way described in Section 15.10.3, page 165. Remember that forum names are composed of name pieces separated with '.'. In TSX-BBS each name component can have read, write, and control privilege expressions associated with it. Privileges in earlier parts of the name apply to later parts of the name. As an example, assume we have the forum "alt.cooking.chili". and assume that the sysop defines the privilege "S50" and decides that this will be associated with read privilege for forums. Chapter 9. Discussion Forums and Newsgroups 100 If the read privilege "S50" is associated with "alt" then the read privilege "S50" is automatically associated with "cooking" and "chili". This property is called inheritance and makes it very easy to assign a specific privilege to an entire hierarchy of forums. If, for example, there were another forum called "alt.cars.ford" then the user would have to have privilege "S50" in order to access it because the "S50" associated with "alt" is inherited by the "cars.ford" portion of the name. It is important to note that that it is not necessary to have an actual forum associated with the name where the privilege resides, although there can be an actual forum there. In the example just given there are two forums: "alt.cooking.chili" and "alt.cars.ford". The privilege "S50" is associated with the name "alt". Note that there is not a forum called "alt"; it is just a part of the name of other forums. If there were a forum called "alt" (and that would be permissible) a user would have to have "S50" privilege to read it. As another example, assume that we define the privilege "S60" and assign it to be the read privilege for the name "alt.cars". Thus, in order to read "alt.cars.ford" the user must have two privileges, "S50" in order to see forums underneath "alt" and "S60" in order to see forums underneath "alt.cars". Privilege inheritance is a very powerful tool which requires some thought in order to be used effectively. As mentioned, there can be read, write, and control privileges associated with every name component. While it is not necessary that every name component have privileges, the flexibility is there for almost any imaginable combination of user access. Also, remember that there are reasonable defaults for forum access so forum privileges are something that you can grow into when the need arises. This concept of inheritance applies in the same way to write and control privilege. While control privilege is more rare, restricting write privilege is a common desire. Since writing to a forum may result in sending messages out to the rest of the world it would be prudent to restrict write privilege to authorized or known users. 9.7 Forum Creation and Access Issues For an introduction to tossers see Section 9.2. One feature of the tossers provided with TSX-BBS is the ability to create new forums. For networks such as Usenet and Fido it is not always easy to find out the names of all the forums because new forums are created periodically. In the case of some networks (such as Usenet) there is no official mechanism to notify sysops that new forums have come into existence. Chapter 9. Discussion Forums and Newsgroups 101 By default, the TSX-BBS tossers will automatically create new forums when messages are received for forums that do not exist. When new forums are created a notification line is written to a log file named BBS:FNEW.LOG. Log files are discussed in Section 9.9. The sysop can use this file to review the new forums and keep or delete them as desired. By default, users can see new forums as soon as they are created. 9.7.1 Restricting the Creation of New Forums While automatic creation of new forums is quite useful there are valid reasons for wanting to restrict this capability. One reason is disk space. Once a forum is created is can begin accumulating messages on all subsequent tosser runs. The other is a matter of focus; the sysop may only be interested in a small subset of topics and will not want to be constantly deleting new forums. There are two tools for handling this. The main tool is simply an option which says whether or not tossers are or are not able to create new forums. This applies to all TSX-BBS tossers and simply disables that functionality. When the tossers attempt to add a message to a forum which does not exists it will attempt to create the forum and fail. A message indicating failure is written to the log file BBS:FERROR.LOG. If tossers cannot create forums the sysop must manually create the desired forums through any of the means available to the SYSOP program; these are discussed in Section 15.10.3. The other tool restricts addition on the basis of the name of the forum. This only comes into play if the global option to create forums is enabled. In other words, if new forum creation is disabled via the global option then this mechanism is disabled. Forum names are composed of name pieces separated by periods. An example might be "alt.cooking.chili". The sysop may specify that no new forums are to be created "under" a certain name. In this context "chili" is under "cooking" and "cooking" is under "alt". For instance, we can modify the "cooking" portion of "alt.cooking.chili" to indicate that no new forums should be created under "cooking". Thus, when a message for the forum "alt.cooking.cajun" came in the tosser would discover that no new forums under "cooking" are to be allowed and the message would be discarded. However, if a message for "alt.cars.fords" came in the tosser would create the forum since there was no restriction on names under "alt". The SYSOP control screen for forums, described in Section 15.10.4, allows the specification of 'Y' or 'N' for autoadd. This enables or disables, respectively, the creation of new forums under the name component being modified. Chapter 9. Discussion Forums and Newsgroups 102 9.7.2 Previewing New Forums Before Users As mentioned, users can see new forums when they are created. There are reasons that the sysop may want to preview the forums before allowing users to access them. The main reason is to confirm that the forum does not contain anything which the sysop may consider to be inappropriate for general access. The other reason is clerical: to confirm that the new forum created is not a misspelled version of another. To prevent users from seeing new forums the sysop uses privilege expressions to prevent read access to the new forums. Privilege expressions and forums are discussed in Section 9.6. In particular, the concept of privilege inheritance can come into play when working with new forum privileges. Examples will illustrate this, but the concept must be understood first. While its use is not required, there is a built-in privilege called "New Forum Review" (P11) which can be used for this capability. When the tosser creates a new forum it assigns values to the read, write, and control privileges for the forum that is being created. The privilege expressions to be assigned to new forums created by tossers are specified in the SYSOP program in the "New forum defaults" screen, discussed in Section 15.10.7.1. By setting the read privilege to P11 in this screen new forums will be created with this privilege. Only users with this privilege or sysop (P14) privilege will be able to review the new forums. As mentioned, the tosser writes a line to the file BBS:FNEW.LOG when it creates a new forum. The sysop may then review these new forums so listed. After deciding which forums to keep, the sysop can reset the read privilege of the desired forums. Resetting the privilege to an empty string will result in the forum inheriting the privileges already associated with its higher level name components. If none of the name pieces has any privilege strings associated with them then users will have read and write access to the forum, but not control access. 9.7.3 Example of New Forum Management To illustrate this, assume that there are no forums and assume that the sysop has set the read privilege to P11 in the "New forum defaults" screen. Also, assume the global "create forums" option is enabled so that tossers may try to add new forums. The tosser runs and a message for "alt.cooking.chili" comes in. The forum will be created and the message added. The tosser writes a line to the file BBS:FNEW.LOG indicating that the forum has been created. The new forum has the read privilege P11. This means that users must have new forum review (P11) or sysop (P14) privilege to see it. It is important to note that the name component "chili" has the new read privilege, not the name component "alt" or "cooking". These components do not have any privileges associated with them. Chapter 9. Discussion Forums and Newsgroups 103 The sysop reviews the BBS:FNEW.LOG file and sees a record about the new forum. After review, the sysop decides to allow general access to the forum. Using the SYSOP control screen for the forum the read privilege is set to null (no expression at all -- blank). Since none of the name components prior to "chili" have any privileges, users will have default access to this forum. They will be able to read messages, post messages, and delete messages which they themselves have already posted. 9.7.4 New Forum Management Using Privilege Inheritance The concept of privilege inheritance can make it easier for the sysop to manage a large number of forums with privilege restrictions. To demonstrate this, let us now assume that the sysop has decided to restrict forum access. Only users with the sysop privilege 36 (S36) are to be allowed any access to forums. The sysop still wishes to preview new forums, however. Assume that the first forum is created as in the previous example. The sysop now needs to set the read privilege to S36 to allow authorized users to see the new forum. There are two ways to do this. The sysop can change the privilege associated with the name component "chili" from its assigned value P11 to S36. This will work as expected; only users with S36 will see the new forum. There is another way to accomplish the same thing which can prove to be more useful when there are many forums. If the sysop sets the read privilege of the name component "chili" to null and sets the read privilege of "alt" to S36 it will still be the case that only users with S36 will be able to read "alt.cooking.chili" because the component "chili" inherited its read privilege from the name component "alt". How is this useful? The next time a forum is created under "alt" the sysop need only reset the read privilege of the new forum to null and the new forum will inherit its read privilege from "alt". When there are many forums under "alt" and the sysop decides to change the required privilege for any reason, there will only be one place which will require the change: the "alt" name component. If the read privilege at "alt" is changed from "S36" to "S36 AND S72" then all of the forums under "alt" will then require that privilege because of inheritance. Had the sysop not done that then every single forum would have had to be modified from "S36" to "S36 AND S72". 9.8 The Forum Control Files and User Access Files There are several control files used with forum access and maintenance. The SYSOP program and TSX-BBS use these to gain access to forum information. It is not strictly necessary to understand the role of the various system control files in order to Chapter 9. Discussion Forums and Newsgroups 104 use or manage forums. The information here is presented for completeness. 9.8.1 Forum Control and Data Files Each forum has one control file and one data file. The names of the files are "Fn.CTL" and "Fn.DAT, where 'n' is the number of the forum. For instance, forum 1234 would have control and data files called F1234.CTL and F1234.DAT, respectively. The two control files for each forum are located in the same directory. The name of the directory which contains the files is derived from the forum number. The directory and files names are automatically created when the forum is created. Briefly, there are three levels of directory for every forum file. The topmost directory is called "FDnnnn" where "nnnn" is the thousands value of the forum number. The second level is named "FDnnn" where "nnn" is the hundreds level of the forum number. The third level is named "FDnn" where "nn" is the tens level of the forum number. For example, forum number 1234 would be located in directory "\FD1000\FD200\FD30\". Again, these directories are created automatically when the forum is created. These directories, in turn, are themselves rooted in directories specified through the SYSOP program. This will be described in Section 15.10.1 page 161. 9.8.2 The BBS:FTREE.DAT File A file named "BBS:FTREE.DAT" contains the forum information used by the SYSOP program. This file is modified when forums are created and deleted and when privileges are set. This file can be re-generated from the forum control files by using the SYSOP option "Build from ctl files". The SYSOP program consults this file for its displays. 9.8.3 The VFILEx.DAT files A set of files named "BBS:VFILEC.DAT", "BBS:VFILEH.DAT", "BBS:VFILEA.DAT", and "BBS:VFILEN.DAT" contain index information which allows users fast access to the forum information. The are ASCII files which are generated by the tossers and by the SYSOP program. They contain a snapshot of what is in the FTREE.DAT file at the time they were generated. All four files are generated at the same time. The SYSOP program can generate these files with the command "Make user access files". Tossers will regenerate these files at the end of their run if they created new forums. When the sysop interactively creates or deletes forums the SYSOP program will notify the sysop that the files need regeneration. The sysop may elect to not regenerate at that time. These files should never be edited. They contain internal offsets which would be easily disrupted by a change in the file size. If Chapter 9. Discussion Forums and Newsgroups 105 changes are needed the SYSOP program should be used to regenerate the files. The files can be regenerated while users are logged on. 9.9 Forum Log Files and the Forum Event Log Forum operations create and append to various log files and to an event log. These files record various levels of detail about aspects of forum operation. All forum log files have names of the form "BBS:Fxxxx.LOG". The forum event log is called FBATCH. The SYSOP program, through the "Log file Options" selection, can enable or disable generation any of these log files. In addition, these log files can be deleted at any time should the need arise. They will be recreated when they are again needed. The use of log files is not required; they are used for troubleshooting and general reporting. There is a program called LOGSWEEP which will trim the log files so that they only keep a specified number of days worth of data. Once properly set up and enabled, the LOGSWEEP program will ensure that the log files do not grow without bound and will allow log files to be used as a historical resource. There are 6 forum log files. A section will describe each of them. All log file entries are preceded by the date and the time. The examples will leave the date and time out for brevity. 9.9.1 FSUMMARY.LOG This log file contains a brief summary of tosser and sweeper operations. Here is a sample of a tosser run: ***** TOSSER starting run Summary of messages added to grand division usenet Messages added = 11 Bytes added = 10674 Duplicates rejected = 0 Messages were rejected due to name restrictions = 0 Forums created = 10 ***** TOSSER ended run Each line is described below: Summary of messages added to grand division usenet --- Each tosser adds to one of the grand divisions. There is a usenet tosser and a fidonet tosser. As more tossers are developed they will add to different grand divisions. Grand divisions are discussed in Section 9.5. Messages added = 11 --- This is the number of messages for all forums from all files. Bytes added = 10674 --- This is the uncompressed byte size of the sum of the messages. Chapter 9. Discussion Forums and Newsgroups 106 Duplicates rejected = 0 --- Attempts to add duplicate messages are rejected. This is the total for this run. Messages were rejected due to name restrictions = 0 --- When the tossers find a message to a forum which does not exist they will try to create it. Section 9.7.1 describes the way the sysop can limit forum creation on a name-by-name basis. This represents the count of messages to forums which did not exist and which could not be created due to name restrictions. Forums created = 10 --- When the tossers find a message to a forum which does not exist they will try to create it. This is the number of forums created by the tosser during this run. Here is a sample sweeper run: ***** SWEEPER run starting at 3-Sep-1994 13:05:36.970 Duration 0 hours 0 minutes 3 seconds 10 forum(s) processed 2 forum(s) skipped Deleted a grand total of 10 message(s), 237 bytes ***** SWEEPER run ended at 3-Sep-1994 13:05:40.770 10 forum(s) processed --- The sweeper will, by default, only process forums which had messages tossed into them. Therefore the number of forums processed may frequently be much smaller than the actual number of forums on the system. 2 forum(s) skipped --- There are circumstances which will cause the sweeper to skip a forum. Deleted a grand total of 10 message(s), 237 bytes --- At the end of its run it reports a grand total of messages and bytes deleted. Tossing and sweeping are the two primary batch forum activities, so the summary file just reports the major statistics from those operations. 9.9.2 FSWEEP.LOG When the sweeper runs it reports on every forum it processes. This report contains detail on each forum. Here is some sample output. ***** SWEEPER run starting at 10-Sep-1994 0:00:02.310 Performing mini sweep Cluster optimization will be performed Number of days override = 4 Number of messages override = 40 Mininum number of messages override = 10 Processing file f:\bbsforum\FD1000\FD000\FD00\F1000.CTL Forum name is usenet.comp.os.ms-windows.programmer.misc 39011 bytes, 37 actual messages, 0 marked deleted, 0 expired Earliest written 09/07/94 01:49. Earliest added 09/08/94 18:43 Chapter 9. Discussion Forums and Newsgroups 107 Processing file f:\bbsforum\FD1000\FD000\FD00\F1007.CTL Forum name is usenet.misc.jobs.resumes 153770 bytes, 42 actual messages 0 marked deleted, 0 expired Earliest written 09/05/94 13:56. Earliest added 09/07/94 21:06 Deleted 2 messages, 174 bytes The sweeper begins by reporting the values appropriate for this execution. There are many options to control the sweeper's behavior. Performing mini sweep --- A mini sweep will only process forums which had messages tossed into them or added to them. Cluster optimization will be performed --- The DOS file system stores files in units called clusters. The size of a cluster varies depending on the size of the disk. Even if a file only has one byte in it it will occupy a cluster on the disk. If the data files for a forum are less than a cluster in size no disk space is recovered if messages are deleted from it. This option, which is the default, tells the sweeper to bypass any forum whose data files are less than a cluster in size. This reduces the time that the sweeper takes to run. Number of days override = 4 --- This tells the sweeper to expire messages which are older than 4 days old. Number of messages override = 40 --- This tells the sweeper to limit the number of messages in a forum to 40. Mininum number of messages override = 10 --- This tells the sweeper to always at least keep 10 messages in the forum, even if they are expired. Each forum processed produces a set of messages. . Processing file f:\bbsforum\FD1000\FD000\FD00\F1000.CTL --- The name of the control file is given to introduce the section. . Forum name is usenet.comp.os.ms-windows.programmer.misc The name of the forum is reported. . 39011 bytes, 37 actual messages --- This is the actual count of messages and the size before sweeping. . 0 marked deleted, 0 expired --- This is a count of deleted and expired messages. . Earliest written 09/07/94 01:49. -- Newest message date. . Earliest added 09/08/94 18:43 --- It is sometimes useful to see the oldest message written and posted to a forum. Chapter 9. Discussion Forums and Newsgroups 108 This first example did not exceed the restrictions specified so no messages were deleted. In the second example messages were deleted. The number of messages and byte count are reported as follows. Deleted 2 messages, 174 bytes 9.9.3 FREJECT.LOG When the tossers find a message for a forum which does not exist they will try to create the forum. Section 9.7.1 describes the way the sysop can limit forum creation on a name-by-name basis. The sysop can also globally disable new forum creation. When forum creation is globally disabled the following message appears in the log file Discarding message to forum usenet.alt.cars due to AUTOADD = 0 When an attempt to create a forum fails due to name restriction a message of the following form appears. Discarding message to usenet.alt.cars due to name restriction 9.9.4 FSTAT.LOG This log file contains statistics about tosser runs. It contains a line about each file that it processes as well as a copy of the same statistics that go to the summary file. Here is a sample showing output from a usenet tosser run. Pre-Processing file DHA0:\TSX32\BBS\FORUM\BATCH\NEWS1490.BAG Pre-Processing file DHA0:\TSX32\BBS\FORUM\BATCH\NEWS1491.BAG Pre-Processing file DHA0:\TSX32\BBS\FORUM\BATCH\NEWS1492.BAG Pre-Processing file DHA0:\TSX32\BBS\FORUM\BATCH\NEWS1493.BAG Pre-Processing file DHA0:\TSX32\BBS\FORUM\BATCH\NEWS1494.BAG Summary of messages added to grand division usenet Messages added = 31 Bytes added = 112922 Duplicates rejected = 0 Messages were rejected due to name restrictions = 0 Forums created = 29 9.9.5 FNEW.LOG When the tossers find a message to a forum which does not exist they will try to create it. If this succeeds then a line is written to this file of the form: Created forum usenet.alt.cars.ford forum number 1378 The sysop can review this list and decide on which forums to keep. Section 9.7.2 describes how to keep users from seeing new forums until the sysop has had a chance to review them. Chapter 9. Discussion Forums and Newsgroups 109 9.9.6 FERROR.LOG Errors during tosser runs are written to this file. The tossers report the following kinds of errors. . Duplicate message detection. . Messages with invalid byte counts. . Messages with records that are over 300 bytes long. . Errors in decoding headers, including: . Unknown source . Unknown subject . Unknown date . Unknown newsgroups . Any system related errors. These have the form TSX error <dddddddd> <function> Where <dddddddd> is an error code and <function> is text related to the problem. These sorts of errors should be reported to technical support. 9.9.7 The FBATCH event log The tossers and the sweeper write to an event log called FBATCH. This event log contains all the messages directed to all event logs. Event logs does not occupy any disk space so there is no reason not to leave it on all the time. This can be viewed from the SYSOP program by selecting the "Display Event Log" function. The event log is most useful as a means of watching ongoing processing. The TSX "SHOW EVENTS" command can also be used to monitor event logs. 9.10 Classified Ads In TSX-BBS, the functionality for classified ads is integrated into forum processing. All the forum functions for creating, maintaining, and deleting forums are used with classifieds. Users browse, search, post, and reply to classifieds just as they would to a normal forum. Classifieds are created using a set of forums under a specified grand division. If the grand division name is "classified", for instance, creating a forum called "classified.boats" will create a classified forum called "boats". Since forums can be created hierarchically, the sysop can elect to have classifieds which allow specification of more detail in the name. For example, you could Chapter 9. Discussion Forums and Newsgroups 110 create forums named "classified.cars.ford" and "classified.cars.toyota", etc. This system allows for efficient management of many thousands of ads by breaking down the areas into manageable sizes. There are some minor differences between classified ads and other forums. These differences were implemented to make it easier for the sysop to manage classifieds. 9.10.1 User interface issues TSX-BBS users view and search for classified forums in the same way as regular forums. By default, users will be able to post (add new messages) to the classified forums. The sysop can restrict this capability by setting up write privileges for the classified grand division name. In this way the sysop could, if desired, force users to mail messages to the sysop first for approval and subsequent posting by the sysop. Privileges and forums are discussed in Section 9.6. Replies to messages in classified forums are not posted publicly; they are sent as private E-mail messages to the person who posted the ad. When users post messages to classified forums the "TO:" field is always "ALL". 9.10.2 Specification of Classified Ad Forums to the SYSOP Program From the sysop's perspective there is only one item which is unique to the forums which are used as classifieds: the name of the grand division. The grand division name is spelled out so that the various components of TSX-BBS are aware of forums which are classifieds. From the SYSOP program main forum menu type 'H' to select the "Housekeeping" screen. From there type 'G' to select the "General forum options" screen. The section "Classified Options" allows specification of the grand division name. The value you must specify is the "Classified ads grand division name". This string must be the grand division name for any forums created as classifieds. Specification of this name enables various aspects of TSX-BBS to be aware when they are processing classified forums. You can choose whatever name you want for the classified grand division. Typical names are "classified" and "ads". Once you have specified the classified ad grand division name and the number of days before expiring messages, you are ready to define the actual forum names. Press ESC twice to return to the main forum menu. From here press 'C' to select "Create" and then press 'C' again to select "Create forum". You will then be presented with a data entry screen titled "Create new forum". In the first field, labeled "Name", enter the name of the forum. This name must begin with the grand division name that you specified for Chapter 9. Discussion Forums and Newsgroups 111 classified ads. In other words, if you specified "classified" as the grand division name, you would give your forums names such as "classified.cars", "classified.boats", "classified.jobs.clerical", etc. Repeat the forum creation process for each classified ad forum. See Section 15.10.3 on page 165 for additional information about creating forums. The sweeper program recognizes that a forum is part of classifieds and will ignore minimum and maximum messages for any such forum. In other words, the sweeper will only delete messages from classifieds based on the expiration date of the messages. The section 9.3 describes how the number of days to expiration can be specified on a forum by forum basis or associated with a class of forums with a common name. As an example of how to associate a single expiration date with all forums under classified, assume that the sysop is using "classified" as the grand division name and assume the sysop has created at least one forum under that name. There is now a name component called "classified" which can be modified with the SYSOP program by going through the "Forum", "Modify and Display menu", "Hierarchical List" menus. Selecting "Modify forum" will display the "Inspect forum" screen. From here the number of days until expiration can be specified, if desired. Chapter 10 Electronic Mail 10.1 Introduction This chapter covers TSX-BBS facilities for sending and receiving private electronic messages. Note that the forum system also has electronic mail, but forums are public message areas divided into message categories. Electronic mail covers messages sent and received for individual bulletin board subscribers. To manage the TSX-BBS mail facility, you need to be familiar with the following terms. . Message bases are database files with messages in them. To maximize efficiency and ease management, TSX-BBS organizes electronic mail into separate message bases. The main message base stores all incoming mail for the subscribers of the board. This includes mail which has been sent from one subscriber to another, as well as mail which has been received from external mail services such as Fidonet or Internet. A separate message base contains messages which users have read and saved for future reference. Finally, there is one message base for each type of outgoing mail (for example, one message base for outgoing Internet mail and one message base for outgoing Fidonet mail). . Area numbers are numeric codes assigned to each message base. Area numbers are also assigned to forums. Forums and e-mail areas are assigned numeric codes for the benefit of offline readers like QWK, which need a shorthand way to refer to the areas which the user wants to process offline. Area numbers are also used internally by TSX-BBS to identify mail routes such as fidonet. . Routes are the methods of transmission of mail message. The "local" route describes mail sent directly between two board subscribers. Fidonet and Internet mail would each be a separate route. There is a separate message base, and a separate area number, for each outgoing mail route. . The "filing cabinet" is the message base containing mail which users have saved for later. 112 Chapter 10. Electronic Mail 113 . "Scanners" are programs which scan message bases, collect outgoing messages, and post the messages in a form that mailer programs such as Front Door require. . "Tossers" are programs which read incoming messages from external mail services and deliver them to the local BBS subscribers or post messages in discussion forums. . "Mailer" programs communicate with corresponding mailers on other computers and send and receive messages. "Front Door" is an example of a mailer program. . The "mail sweeper" is a program which periodically scans through message bases, compressing them by eliminating old messages. Management of each of these mail related facilities is discussed in the following sections. 10.2 Message Bases and Routes Each message base consists of two separate files. The larger of the two is the text file, which contains the text of each message. To make finding messages fast, a summary of each message is stored in a smaller file called the control file. For each message base there will be a text file with an extension of MLD (for mail data) and a control file with an extension of MLC (for mail control). The name of each message base is assigned by the sysop, but the system comes with default names for local mail and the filing cabinet. These include INMAIL for local mail (hence there are two files named INMAIL.MLD and INMAIL.MLC) and MAILFILE for the filing cabinet. As we noted above, there is a separate message base for each mail route. Using the SYSOP program, you set up which routes are supported by your board and assign message bases to each route. See Chapter 15, page 159 for a description of how to do this. The only management of message bases you need to do is to set them up when implementing support for a new message route. Suppose, for example, that you have just become a Fidonet node and need to provide access to Fidonet mail for your users. Using the electronic mail screen of SYSOP, you simply add Fidonet as a supported route by providing a single letter designation (which denotes Fidonet in the mail route menu), and the name for the associated messagebase (such as FIDONET). After you do this, all that is left is to schedule execution of the Fidonet tosser, which is explained below. When you create a new message base, you must identify which supported message base this is by giving it the proper message area number. This area number serves two purposes. First, it provides offline readers like QWK a way to denote which areas the user wants included in offline processing. Second, the area number is used by Chapter 10. Electronic Mail 114 tossers and scanners to query the system for the name of the message base they are supposed to be processing. This means that the area numbers are not arbitrary numbers you can assign, but are assigned for each message route for which support is provided by S&H. The area number designation for routes such as Fidonet and Internet is specified in the support kit for each route. If you subsequently dropped support for Fidonet, you will return to the SYSOP mail screen and erase the information about Fidonet. This would eliminate Fidonet from the mail route menu, but you must delete the message base files (FIDONET.MLD and FIDONET.MLC) by hand when you are ready to do so. 10.3 Scanners and Tossers For each external (non local) mail route, there must be a way for messages to be sent out of your board, and a way for incoming mail message to be delivered to your subscribers. Each route must therefore include a scanner program to send outgoing mail and a tosser program to receive incoming mail. This means that when you install support for a new mail route, you must copy the tosser and scanner programs onto your hard disk and take steps to ensure that they will be executed when needed. Normally scanners are run on a periodic basis, such as once or twice a day. Each time it runs, the scanner will read the message base to see if there is new outgoing mail to be sent. Each scanner is written to take whatever actions are appropriate to send the mail (such as dial a phone number and upload messages to a provider service). You will want to use the SYSOP scheduling screens to activate each mail scanner at the times of the day you want the mail to be sent. The scheduling screen is described in Chapter 15, page 148. Some tossers may be invoked automatically, in which case they do not need to be scheduled. For example, you can configure some Fidonet mailer programs such as Frontdoor to invoke the Fidonet tosser program each time new mail is received. Other tossers, such as those which dial a mail service and query it for new incoming mail, must be scheduled for execution just like the mail scanners are scheduled. Specific information about each tosser and scanner is included in the chapter which discusses that option. For example, use of the Fidonet tosser and scanner is documented in chapter 19. 10.4 The Mail Sweeper Messages continue to accumulate in message bases, which will grow in size, until the message sweeper runs to compact the message base by eliminating old and unwanted mail. The mail sweeper program, MSWEEPER.EXP, must be scheduled just like tossers and scanners, for Chapter 10. Electronic Mail 115 periodic execution. Since the mail sweeper must wait while people are accessing the mail files reading messages, you will probably want to schedule its execution for late at night when traffic on the board is at a minimum. The mail sweeper will eliminate unwanted messages for several different reasons. First, incoming messages which have been deleted by the user are cleaned up. For an outgoing message base, messages which have been sent by the mail scanner are erased in the periodic mail sweep. Finally, you may specify an age limit for unprocessed mail. This cleans up very old outgoing mail which was never sent (perhaps because the message service was unavailable for a long time), as well as incoming letters which it appears the recipient will never get around to opening. The age limit for messages is specified in the same SYSOP screen used for mail route management. 10.5 Managing local mail Once the local mail system is set up, no ongoing management should be needed at all. In fact, TSX-BBS comes preconfigured with a local message base and a filing cabinet, appropriate default values for message limits for each defined user class, and a reasonable schedule for the mail sweeper. 10.6 Filing Cabinet The filing cabinet provides your users a place to store messages on a long term basis. These may be messages that they have received and want to refer to later or messages which they periodically send out. There are two ways that you can prevent the filing cabinet message base from growing too large. First, each user has a limit on the total number of messages he is allowed to store in the filing cabinet. This limit is normally a function of the user class, but can be customized for each individual user. This user attribute is specified by the "Message limit" field in the user information screen. See Chapter 15, page 142, for information about using the user information screen. The second way that you can prevent the filing cabinet from consuming your hard disk is to place a separate age limit on messages stored in the filing cabinet. This limit is different than the age limit for incoming and outgoing messages because the filing cabinet is, by definition, a long term storage area for mail so you may want to place a much more liberal age limit (such as a year) on it. Chapter 10. Electronic Mail 116 10.7 Accessing Mail from Menus The system comes preconfigured with an electronic mail menu named MAIL.MNU. If you examine this text file, you will see that each mail function included in the menu has an associated action name which it invokes. If you customize your menus and want to include mail functions in customized menus, you should use the same menu actions which are used by MAIL.MNU. These actions are: . MAILSYSOP sends a message to the sysop. The recipient of such messages is the person named in the "Sysop 1" field of the general setup screen. See page 140 for more information. . MAILRECV is used to scan incoming mail. . MAILSEND is used to write a new message. This action is used for sending via all the routes you support on your board. . MAILRECV is used to read incoming mail which has been addressed to the user. A user can never read the mail addressed to somebody else. . MAILSYN allows the user to designate synonymous names by which his mail can be accessed. . MAILABOOK allows the user to manage a person address book, used to enter shorthand designations of his correspondents. This is especially useful for sending Internet messages, since their addresses can be long and difficult to type. . MAILFILE allows the user to browse the filing cabinet for his stored messages. . MAILBROWSE is used by the sysop to view all the messages in a message base, regardless of the sender or recipient. Chapter 11 Censoring Messages One of the primary purposes of electronic bulletin boards and networks is to promote communication between people. However, some people object to messages containing profanity that can be found in public forums -- especially some of the Usenet forums. This can be especially troublesome for public access bulletin boards that allow minors to read forum messages. TSX-BBS provides two mechanisms for restricting access to forums and messages that may be objectionable: 1. Forums may have privilege expressions associated with them which restrict which users can access them. This allows you to set up adult forums that can be accessed only by properly authorized users. Forum privileges are discussed in Section 9.6 starting on page 99. 2. A "word censoring" facility is built into TSX-BBS. If enabled, this facility will store '*' characters over specified words; or, you can leave the first character of the word and store '*' over the remaining characters. This chapter discusses the word censoring facility. 11.1 Word Censoring Facility Many users enjoy the unrestricted nature of the Internet and take a libertarian view to the content of messages posted in Usenet conferences. If you are one of those people, you are welcome to leave the TSX-BBS word censoring facility turned off. In this case, TSX-BBS will present messages exactly as they are received. However, some sysops are concerned about displaying messages with profanities on public bulletin board systems frequented by minors. This can be an especially sensitive issue for schools that assign students to read Usenet messages. If you wish to censor certain words TSX-BBS has the facility to do it. You can even enable word censoring for some users but disable it for others. 11.1.1 CENSOR.DAT File When word censoring is enabled, TSX-BBS scans each message as it is displayed or downloaded. It compares each word in the message with a list of words that you place in an external file named BBS:CENSOR.DAT. If TSX-BBS finds a word in the message that is in 117 Chapter 11. Censoring Messages 118 your censor list, the word is replaced by '*' characters. For each word in your list, you can specify if all of the characters of the word in the the message are to be replaced by '*' characters or whether the first letter of the word is to be left alone and the following letters replaced by '*'. When the matching is performed, TSX-BBS compares the first part of each word in the message with each word in the censor list. If a word in the list matches the beginning portion of a word in the message, the '*' replacement is performed on the part that matches. In other words, a suffix on the end of the word does not have to match the word in the censor list. Depending on options you specify, either all of the word that matches is replaced by '*' characters or all but the first letter is replaced. For example, if "kill" is a word to be censored, then when it is found in the message it will be replaced by "k***" or "****". If the word "killing" is encountered, it is replaced by "k***ing" or "****ing". The way the comparison is performed, a word in the censor list would not be found if it is embedded in another word. For example, the censor word "kill" would not be found in the message word "overkill". However, it would be found in a hyphenated word such as "over-kill". In some cases it is desirable to require an exact match between a censor word and a word in a message without allowing suffix variations. For example, if the word "ass" is a word to be censored and exact matching is not required, then the word "assume" would be replaced by "a**ume". If you specify exact matching for "ass" then "assume" would be left unchanged. If you specify exact matching, you may need to put in plural forms of the word in your censor list. If you wish to use word censoring, the first step is to use an ascii editor and create a file named "CENSOR.DAT" in the "BBS:" directory (by default this is C:\TSXBBS\DATA\). This file contains the list of words that you wish to censor. You must specify exactly one word per line in the file. In addition to the word to be censored, you may specify one or more of the following options on the same line following the word: EXACT -- Specifies that the a word in the document must exactly match a word in the censor list without allowing suffix variations. ALL -- Specifies that all characters of a matching word are to be replaced by '*' characters. If this option is not specified, the first character of the word is left unchanged and the remaining characters are replaced by '*' characters. The following is an example of a CENSOR.DAT file: democrat ass exact kill all Chapter 11. Censoring Messages 119 11.1.2 Censor Control Privilege In some situations it is desirable to allow some BBS users to read uncensored messages and others to have messages censored. TSX-BBS allows this by providing a privilege called "See uncensored text" (P18). If a user is given this privilege, the user is allowed to read uncensored messages. If a user does not have this privilege, and a BBS:CENSOR.DAT file exists, the user will receive censored messages. Note: word censoring only affects messages as they are displayed or downloaded. Censoring is not applied to outgoing messages generated by BBS users. Enabling word censoring increases the time to collect messages for QWK downloads by about 3%. Of course, it has no effect on the time taken to compress the QWK packet or download it. Chapter 12 Internet Access With the optional "Internet Connection Package" for TSX-BBS, your users can have on-line, real-time connections to Internet sites around the world. The Internet Connection option is not available for the demonstration, shareware version of TSX-BBS. The TSX-BBS Internet Connection option provides the following components: FTP (File Transfer Program) -- Allows you to send and receive files through the Internet. With FTP you can do directory listings on remote computers, move up and down through the directory tree, and transfer files to and from the TSX-BBS system. Telnet -- Telnet is a terminal emulator program that allows you to log onto remote computers through the Internet. With Telnet, you can run programs on computers around the world. SMTP (Simple Mail Transport Protocol) -- Allows you to send and receive electronic mail messages through the Internet. The SMTP client and server program are used, respectively, to send and receive email messages directly to and from other computers connected to the Internet. These programs work in conjunction with the SMTP scanner and tosser programs so that Internet mail is fully integrated with the BBS. Incoming SLIP connections -- This allows your users to call your BBS, log on, and then shift from an ASCII type connection to a SLIP (Serial Line Interconnect Protocol). They are then connected to the Internet through your BBS. You can limit which users are authorized for SLIP connections. The normal BBS usage limits also apply to SLIP connections. A menu file named "INTERNET.MNU" is included with your TSX-BBS distribution which contains entries to start FTP and Telnet, and enter SLIP mode. It also includes an entry to manage the user's personal file workspace. 120 Chapter 12. Internet Access 121 12.1 FTP -- File Transfer Program FTP is the program used to transfer files between your TSX-BBS system and a remote Internet site. Using FTP you can perform the following operations: . Connect to another site. . Change between directories on the remote computer. . List files in directories on the remote computer. . Transfer files from your TSX-BBS computer to the remote computer. . Transfer a file from the remote computer to your TSX-BBS system. Since FTP always transfers files between the Internet and a directory on your BBS computer, it is necessary for a user to have a "Personal File Workspace" in order to use FTP. To receive a file through Internet, FTP is used to accept the file and store it in the user's personal file workspace. The file can then be downloaded from the workspace to the user's personal computer using X/Y/Z-modem. Similarly, to send a file, a user first uses X/Y/Z-modem to upload the file to the personal file workspace and then uses FTP to transfer the file through the Internet. See Chapter 8, starting on page 85, for information about personal file workspaces. A user must have built-in privilege P16 enabled in order to use FTP. The menu action code to start FTP is "ftp". The form of the action code is: action=ftp(menu_type[,drop_file]) where 'menu_type' is a numeric parameter that determines the default type of menu that FTP presents to the user. The following three values may be specified: 0 -- Traditional FTP command mode. In this mode FTP displays the prompt "FTP>" and accepts commands terminated by Enter. Refer to an Internet reference book for information about FTP commands. You can type "HELP" or "HELP command" to get help on FTP commands. 1 -- Hot key menu mode. A menu is displayed with the most common commands (get file, put file, quit, etc.) and the user can select a menu item by pressing the single "hot key" character of the command. 2 -- Menu line mode. A menu is displayed with a set of FTP commands and the user selects a command by typing the letter for the command and then Enter. Chapter 12. Internet Access 122 The 'drop_file' argument is optional and usually is not specified. If you do not specify a drop file name, TSX-BBS prompts the user for the name of the host computer to which he wants to connect, and a user name and password that is used to log onto the remote computer. TSX-BBS then builds a "drop" file containing commands with the information the user enters and starts FTP in such a fashion that it initially executes the commands in the drop file. You can also make your own custom drop file. In this case you must specify the device, directory, and name of the drop file as the "drop_file" argument to the ftp action. If you create your own drop file then the first argument to the ftp action, "menu_type", is ignored. You may specify 0 for it. The following commands may be placed in the FTP drop file: HOST name -- Specify the name of the computer to which the connection is to be made. The "name" argument can be either an alphanumeric name such as "sandh.com" or a numeric IP address in "dotted" notation such as "199.1.88.37". USERNAME string -- Specify the user name to use for the logon. If this command is omitted, the remote computer will prompt the user to log on. PASSWORD string -- Specify the password to use for the remote logon. If this command is omitted, the remote computer will prompt the user for a password. SIZE value -- Specifies the maximum number of bytes of data that the user can fetch from the remote computer to the local computer. If this command is omitted, or the value is zero, there is no limit placed on the number of bytes that can be transferred. This command does not limit the number of bytes that can be sent from the TSX-BBS system to the remote computer. TIME value -- Specifies the maximum length of time that the user may remain connected to the remote computer. The 'value' parameter is in units of seconds. MENUACT -- Specifies that FTP is to run in menu mode with hot key activation. MENUCMD -- Specifies that FTP is to run in menu mode and that menu actions are to be selected by typing the command letter followed by Enter. If neither the MENUACT nor MENUCMD commands are specified, FTP starts out in traditional command mode. COMMANDS -- Specifies the start of a block of FTP commands. Following the "COMMANDS" command you may place any of the traditional FTP commands. The command section is terminated when the end of file is reached or a line is encountered consisting of four dollar signs ("$$$$"). Chapter 12. Internet Access 123 Comments -- Comment lines may be placed in the command file by beginning each comment line with an exclamation point. The following is an example of a complete FTP drop file: HOST SANDH.COM USERNAME ANONYMOUS PASSWORD JONES MENUACT COMMANDS ls $$$$ If these commands were in a file named "C:\BBS\FTP.CMD" then the following command could be placed in a menu file to cause FTP to be started with these commands when the letter 'F' is typed: $item key=F action=ftp(0,c:\bbs\ftp.cmd) 12.2 Telnet -- Internet Terminal Session Telnet is a terminal emulator program for the Internet. Using Telnet you can log onto computers accessible through the Internet and run programs remotely. The menu action code to start Telnet is "telnet". The form of the action code is: action=telnet[(host_name)] where host_name is an optional argument that specifies the name of the host computer to which the Telnet session is to connect. If you do not specify a host_name argument, TSX-BBS prompts the user to enter a host name. For example, the following command in a menu file would start Telnet when the letter 'T' is typed and cause TSX-BBS to prompt the user for the name of the host to connect to: $item key=T action=telnet 12.3 Internet Mail (SMTP) 12.3.1 Introduction The Internet Connection Package includes the SMTP client program, SMTPC.EXP, which sends outgoing Internet mail, and the SMTP server program, SMTPS.EXP, which receives incoming Internet mail. The relationship between these programs and TSX-BBS is identical to the way a mailer program such as Frontdoor sends and receives Fidonet mail. Chapter 12. Internet Access 124 For outgoing mail, the sysop sets up a message base which will store messages waiting to be transmitted. Setting up message bases is discussed in section 15.9. For incoming mail, the tosser program is periodically run to gather the messages and write them into the local message base. This allows a TSX-BBS user to receive messages from around the world just as easy as receiving messages from other users of the local board. 12.3.2 Setting up Internet Mail The following list describes each step you should take to implement Internet mail for your BBS. . Get on the Internet. This probably means that you will need to contact an Internet provider and subscribe to a service. . Set up the message base for outgoing Internet mail (see page 159 for instructions). You must use the message area number 2 for your Internet message base because this is the way the scanner program for outgoing Internet mail locates it. Once you have completed this step, your users will see the Internet option on the route selection menu for outgoing mail messages. . Go into the Internet configuration screen in SYSOP. This is a submenu of the mail configuration screen, so type `M' from the top level menu for "Mail", then `I' from the mail menu for "Internet". Enter the name of your Internet node (such as MYNODE.EDU or MYNODE.COM) in the domain name field. Specify the name of the person to receive undeliverable incoming mail, if any. Save your selections by pressing ESC. . Use the scheduling screen in SYSOP to schedule the scanner program to scan outgoing Internet messages. Use of the schedule manager is described in Chapter 20. . Ask the schedule manager to periodically run the Internet tosser procedure to toss incoming Internet messages into the local message base. 12.3.3 The Internet Scanner Outgoing Internet mail is scanned by the SMTPSCAN program, SMTPSCAN.EXP. Normally there is no need to qualify the SMTPSCAN invocation or include any other commands when it runs, so the event which is specified to the schedule manager is simply SMTPSCAN.EXP. Each time the scanner runs it searches the outgoing Internet message base you set up for messages which are waiting to be sent. Each such message is extracted and formatted into a temporary file in the SMTPOUT subdirectory of your BBS area. These temporary files are given sequentially numbered names and have the extension of SOU. Chapter 12. Internet Access 125 For each file generated, the scanner program will invoke the SMTPC client to perform the actual work of sending the message. The operation of the SMTPC and SMTPS client and server programs are described fully in the TSX Networking manual. When the SMTP client program runs, it will create a log file documenting the transactions which take place with the server program on the remote computer which receives the message. The name of this file matches the temporary file which stores the message text, and has the extension of LOG. When the SMTP client program exits, it exits with a status code of 0 to indicate that the message was successfully sent, or non zero if the message was not successfully sent. If the message can not be delivered, the SMTPSCAN program will read this log file and send it back to the inbox of the user who sent the message so that the user can analyze why the message was not sent, take corrective action, and resend it. Examples of why a message might not be delivered include that the host name was not recognized or that the recipient was not recognized by the SMTP server program on the host. The SMTP scanner program can be manually invoked by the sysop with command line qualifiers as follows: SMTPSCAN [/RESEND] [/FLUSH] The /RESEND qualifier is used to resend all messages which are currently in the outgoing SMTP message base. The /FLUSH qualifier does not actually send any mail, but declares that all messages currently in the message base have now been sent. 12.3.4 The Internet Tosser Incoming Internet messages are received by the SMTP server program, SMTPS, and placed in the SMTPIN subdirectory of your BBS directory. You should ask the schedule manager to periodically run the SMTPTOSS program, which reads the temp files containing each message and delivers them to the recipients by writing them into the local message base. Normally there are no other commands needed to run SMTPTOSS and no qualifiers required for the SMTPTOSS command, so the event which is declared to the schedule manager is simply SMTPTOSS.EXP (there is no batch file with commands to run the tosser program). However, the SYSOP may run the SMTPTOSS program manually at any time using the following command syntax: SMTPTOSS [/DIRECTORY=dirname] [/SAVE] Normally the SMTPTOSS program will look for the temporary files with the extension of SIN which the SMTP server leaves in Chapter 12. Internet Access 126 BBS:\SMTPIN\. You may specify an alternate directory to search for *.SIN by specifying its name using the /DIRECTORY=name qualifier. Normally the SMTPTOSS program deletes the temporary files once it has delivered them to the local message base. You can ask that SMTPTOSS save these files by specifying /SAVE on the command line. Chapter 13 Chat Chat is an online conferencing feature which allows concurrent users of your board to carry on group discussions. This chapter explains how chat works. 13.1 Discussion Groups The TSX-BBS chat facility is oriented toward discussion groups. You can think of chat as a room full of people talking to each other. The people are clustered into groups, with each group engaged in discussing a different topic. When a person in a particular group make a statement, all the other members of that group listen, but people who are engaged in different discussions do not pay any attention. Before your users can chat, they must first join an existing discussion group or create a new one. Since most people feel more comfortable joining an ongoing conversation that striking up a new one, the sysop can create any number of permanent discussion groups for people to enter. When two or more people are in a group, an online conversation can take place. You will probably want to create one or two general groups which most people will join. You might want to give them names like "chat lounge" or "general discussion". If your board has a large number of users, you may also want to create specialty groups like "politics" or "music". Creating permanent discussion groups is done using the SYSOP program. The data entry screen used to create and delete discussion groups is described in section 15.5, page 153. 13.2 Chat handles Users with sufficient privilege may declare "user handles" for themselves. This privilege is built-in privilege number 10 (P10), and is displayed by the SYSOP program as "use handles". The sysop may control whether handles are allowed to be used at all and under what circumstances they may be used. Handle control is set up using the SYSOP program as described in Section 15.7. 127 Chapter 13. Chat 128 Users themselves can have two different ways they can set their own handle. First, the user configuration menu includes an option named "handle name". Second, the chat menu itself includes an item named "chat handle", which invokes the menu option named "chathandle". Both of these options in fact set the same handle. Users with P10 privilege may declare this handle, which then shows while they are in chat, and is also displayed when other users see who is on the board. Note that these options will not appear on the menus if the user does not have the privilege to use handles. The handle selected by the user is displayed by the SYSOP program in the userlog screen. The sysop may change the handle from this screen. 13.3 Scrolling The TSX-BBS chat system features split screen chat, but only for those users whose communication software is capable of partial screen scrolling. Partial screen scrolling means that the BBS sends out escape sequences which cause a range of lines on the screen to be scrolled up while leaving the portions of the screen outside that range unaffected. If users can support scrolling, chat uses the upper two thirds of the screen to show messages from members of the discussion group, and the bottom portion of the screen for the user to compose his own input. If a user has specified that he can not accept ANSI escape sequences, TSX-BBS never attempts to use scrolling regions for chat, since the sequences to perform scrolling are an ANSI extension. If the user does accept ANSI sequence, TSX-BBS will ask the user to conduct a scrolling test the very first time that the user accesses the chat system. This test will display marker lines at the top and bottom of a scrolling region, then attempt to cause multiple lines to scroll within the marked region. The user must then tell TSX-BBS whether the display lines scrolled within the marked region. After this test has been conducted once, TSX-BBS will remember the setting. This setting also appears in the user log screen, and can thus be set by the sysop at any time. Chapter 13. Chat 129 13.4 The chat user interface There are separate menu actions for setting the handle, finding out who else is in chat, joining an existing discussion group, and creating a new discussion group. As TSX-BBS is shipped, all these options are offered from the chat menu named CHAT.MNU. One of the minor modifications you may want to make to the chat menu is to remove the option to create new discussion groups, or require some privilege to create new discussion groups. You are also welcome to change the menu structure entirely and place options to activate the various chat actions throughout your revised menu structure. 13.4.1 Changing handle When a user asks to change his chat handle, he is simply prompted with the current handle and allowed to enter a new one. Note that the new handle must be "registered" with TSX-BBS, which ensures that no two users of any board are allowed the same user handle. 13.4.2 User list When a user asks to see who else (if anybody) is in chat, he is presented with a screen that looks like this: Users currently in chat [ 1] Cappannari [ 2] Red Baron in group Healthy Eating [ 3] Red Neck in group Racetrack [N]ext [P]rev [Q]uit: In the event that more than one page of users is displayed, the user uses the next and previous keys to view each page, and then selects quit to return to the chat menu. Note that there is also an option to view the users while currently in a discussion group, as described below. 13.4.3 Creating a discussion group If a user asks to create a discussion group, he is prompted with the name of the new group. After doing this, the user immediately "joins" the new group, where he must wait for a second user to see the group and join. Note that when the last participant finally leaves a group which has been created by a user, the discussion group will disappear. Only the sysop is allowed to create permanent discussion groups. Chapter 13. Chat 130 13.4.4 Joining an existing group If the user asks to join a discussion group, he is placed in a browse screen similar to the one shown below: Chat discussion groups [ 1] Chat lounge (12 members) [ 2] Religion (no members) [ 3] Healthy Eating (1 member) [N]ext [P]rev [Q]uit or enter group number to join group: The user may use the next and previous keys to move between pages in the event that there is more than one page of discussion groups to display. Finally the user must either join a group by typing the number or quit, which returns to the main chat menu. 13.4.5 Reading and writing chat messages Once a user joins a discussion group, the way chat operates will depend on whether the user's communication software can perform partial screen scrolling, as described above. In either case, the user will see the contributions to the discussion made by all the other participants in the group. Each line of text from other users will show the BBS line number that member is on, followed by the user's name or handle, followed by the text of the message: (7) Argia: How are you doing, ACE? In order to contribute, the user simply types in one or more lines to be sent to the other members. The user may correct typing errors offline. The text is not sent to the other members of the group until the user presses the ENTER key. In the case that the user supports scrolling, the upper portion of the screen is used to display output from other users while the lower portion of the screen is used to compose a contribution. Users who can do scrolling will continue to see the contributions of other users while they compose their own. However, in the non-scrolling case, output from other users will be suppressed while a message is composed. 13.4.6 Chat commands While participating in a chat group, the user may type special commands which cause actions to be taken instead of sending messages to the other members of the group. For example, to exit the group the user types a line starting with "/Q". To find out who is in chat, the user can type "/W". Finally, to send a private message to another member, the user can type a slash, followed by the line number of the recipient, followed by the text. For example, to send a private message to the member who is on line 7, the user might type: Chapter 13. Chat 131 /7 Hey Argia, want to have lunch one day this week? When a private message is sent, the sender's line number is preceded by a "P" to denote private mail. Suppose that the sender of this private message was on line 10: (P10) Skullman: Hey Argia, want to have lunch this week? 13.5 Colors For users with color displays, chat differentiates from messages from other members, a user's own contribution, and messages from the chat system itself by displaying them in different colors. You customize these colors using the SYSOP program. This is described in chapter 3. 13.6 The chat server In order to be able to use chat, TSX-BBS runs a detached daemon process named the chat server. This process runs the program file named BBSBIN:CHSERVER.EXP. The chat server is detached from the system STARTBBS.CMD command procedure, and should require no maintenance. If the server ever does fail, you should provide the file BBS:CHAT.LOG to S&H for analysis. 13.7 Chat menu options Normally the chat system is presented to a user from a single menu which can invoke each of the chat functions. However, since you are welcome to rearrange menus to suit your needs, you may want to invoke the chat functions from different menus. This section documents what the chat menu functions are. These are the actions which you use in the ITEM statements of a menu. For example, the ITEM statements in the standard chat menu are: $item key=J action=chatjoin $item key=C action=chatmake $item key=H action=chathandle $item key=U action=chatuser $item key=Q action=return $item key=(other) action=return The chat menu actions are explained below. . Chatjoin -- Used when a user wants to view the discussion groups and possibly join one. This action will show the user a browse list of all the existing discussion groups if there are more than one. However, if there is only one existing discussion group this menu is bypassed and the user immediately joins the one group. Chapter 13. Chat 132 . Chatmake -- Used when a user wants to create a new discussion group. . Chathandle -- Used to allow the user to change his chat handle. . Chatuser -- Used when the user wants to see a list of all the users who are currently in chat. Chapter 14 Door Programs A "door" is an external program that is not part of the TSX-BBS software system. Doors are stand-alone programs that usually are designed to run directly under DOS; normally they are in the form of ".EXE" program images. The most common type of door programs are games. Note: Although most door programs run well with TSX-BBS, there are some door programs that will not run with TSX because they do tricky operations that depend on the real DOS operating system being present. The first step in setting up a door program is to install it and attempt to run it with TSX as a stand-alone program in "local" mode. The method to use for running a door in local mode depends on the door; many doors require you to set up an initialization file with "COM0" as the communication port device name. Also note that some door programs put an extremely heavy load on the system -- equivalent to dozens of users running TSX-BBS sessions doing other things such as file library browses. So, you should do some experimentation after installing a door to make sure it will not adversely affect the performance of other users. Section 14.5 on page 138 discusses how you can "tame" a door program so as to minimize its impact on the system. Before discussing how door programs can be run with TSX-BBS, let's review how door programs operate with traditional, single-user BBS systems such as Wildcat and PCBoard. With these systems that can only run one user and one program at a time, the BBS software runs most of the time and monitors the phone line for incoming calls. When a user connects and selects a door program from the BBS menu, the BBS does one of two things: it either exits to DOS with an exit status code that can be used by a BAT file to determine which door to run, or it loads the door into memory with the BBS software and transfers control to it (this method is not commonly used because there is usually not enough memory available to run the BBS software and the door at the same time). In either case, once the door begins running it takes control of the COM port controlling the modem so that it can accept commands from the user and display screens that will be sent to the user. Some door programs also update the console screen image so that the sysop can observe what is going on. When the user exits from the door, control returns to the BBS system which resumes control of the COM port. 133 Chapter 14. Door Programs 134 14.1 Running Door Programs with TSX-BBS TSX-BBS uses a more elegant but slightly more complex method for running door programs. Since TSX-BBS is part of a true multi-user and multi-tasking operating system (TSX-32), it is capable of running multiple programs at the same time. When a user requests that a door program be run, TSX-BBS initiates ("forks") a "child" subtask to execute the door. The TSX-BBS program continues to exist as an active process but it does not not consume any processor time because it goes to sleep while waiting for its "child" process, the door, to complete. However, because the TSX-BBS process is still active, it can continue to monitor the communication line for loss of carrier. It also watches for the user running out of authorized connect time. When the door program terminates, a status message is sent to the parent TSX-BBS job which resumes execution. The subtask ceases to exist once the door completes its operation. 14.2 Terminal I/O from the door program Because of the way door programs run with DOS BBS systems, they are written to communicate with the user through a COM port. Some door programs do this by directly programming the UART controller that is part of the COM device; other door programs do their terminal I/O using a "FOSSIL" driver. TSX-BBS supports both types of terminal I/O. TSX-32 supports many types of serial communication controllers including "intelligent" serial multiplexers that offload some of the processing from the CPU. Because these devices do not have standard COM port type controllers, TSX-32 includes a software facility known as "virtual UARTs" that allows programs written to use standard COM ports to run with any type of serial controller supported by TSX-32. The virtual UART facility emulates the operation of the actual hardware devices and make all adapter types look like simple UART COM ports for communication programs that perform direct COM port I/O. This emulation forces TSX to intercept all IN and OUT instructions performed to the COM port control registers by the door program, and convert them into the appropriate commands depending on the type of serial adapter actually in use. This emulation allows programs like doors and communication programs such as Procomm to use any serial line on any type of adapter that is supported by TSX even though these programs do not understand how to control the actual hardware. TSX makes it "look" like a 16550 UART type COM port. This emulation works well but may result in high-speed communications being slowed down because of the emulation overhead. The use of actual 16550 type buffered controllers or intelligent multiplexers reduces the overhead and improves throughput. It is highly recommended that you use the TSX "HOST" command to place outgoing modem calls and do uploads and downloads rather than using programs like Procomm because the HOST command does not use the UART emulation and is much more efficient. Chapter 14. Door Programs 135 A "FOSSIL" driver is a DOS program that serves as an interface between a program such as a door and the actual hardware COM ports. The programs perform system services to send and receive characters and the FOSSIL driver performs the low-level programming of the COM ports (or other devices in some cases). The most popular DOS FOSSIL drivers are BNU and X00. TSX-32 has a FOSSIL driver built into it so you do not need to use any other FOSSIL driver. When installing a door program for use with TSX-BBS, you should tell it to use the FOSSIL driver if this is an option. In general, I/O done through the FOSSIL driver is more efficient than using virtual UARTs. If the program gives you a choice of COM ports, tell it to use COM port 1 with a base port address of 3F8 and IRQ (interrupt) level 4. Note that all door programs should be directed to COM port 1 regardless of the actual serial line that the user is connected through. TSX redirects COM port 1 I/O to the actual controlling terminal line while the door is running. If multiple copies of the door program are running, each one "thinks" that it is talking to COM port 1 but the actual I/O is sent to the line for the user who is running the door. 14.3 Drop Files Most door programs need to be passed some information from the BBS system to tell them which COM port to use, the name of the user, the maximum time that the user may run, etc. These information files are known as "drop" files. There are several types of drop files and some door programs require a particular type, others can be instructed to use one type or another. There are also conversion programs available to convert one type of drop file to another. The most common type of drop file, and the one used by TSX-BBS, is a DOOR.SYS file. If you have a choice during the installation of the door program you should select DOOR.SYS as the drop file type. When a user requests execution of a door program, TSX-BBS creates a DOOR.SYS file with information about the user such as the user's name, the number of minutes of connect time remaining, etc. Because many users can be running door programs at the same time, TSX-BBS places the DOOR.SYS file in a temporary directory to keep it separate from the DOOR.SYS files for other users. The name of the temporary directory is "TMPnn" where "nn" is a user identification number that uniquely identifies each user. This directory is a subdirectory of the main BBS temporary directory. The main temporary directory can be specified using the SYSOP program; it defaults to "C:\BBSTEMP\". So, for example, if a user with an ID number of 4 runs a door program, the DOOR.SYS file would be placed in a directory named "C:\BBSTEMP\TMP4\". The temporary directory is deleted when the user logs off, along with any files in it. Usually, you do not need to be concerned with the actual temporary directory name because you can use the @tempdir@ Chapter 14. Door Programs 136 substitution operator to pass the directory name to the door program. 14.4 Setting up Menu Entries to Run Doors Most commonly, door programs are started by selecting items from menus. However, there is also a function in the TPL programming language for starting a door. This section explains the details of setting up menu items for starting doors, see Chapter 5 for general information about creating menus. The "door" menu item action is used to start execution of a door. The door action begins execution of an external "door" program. The form of the action is action=door(cmdline[,message[,activity]]) where 'cmdline' is the command line that is to be passed to the TSX command interpreter to execute the door batch file, and 'message' is an optional argument that is displayed on the user's screen while the door program is being started. You can specify something like "Starting chess" to give the users something to look at while the door is getting started. The 'activity' argument is also optional. If specified, it is a string to be displayed as the current activity for the user while the door is running. For example, you might set the activity to "Chess" while the chess program is running. The 'cmdline' argument usually begins with the name of a batch file that gets the door started. You can use either DOS style BAT files or TSX style CMD files to run door programs. It is best to specify the extension as part of the file name along with the device and directory where the batch file is stored. After the name of the batch file you can specify one or more arguments to be passed to the batch file. For example, the following command would run a batch file named CHESS.CMD and pass the argument string "advanced" to it: $item key=C action=door("c:\chess\chess.cmd advanced") Substitution operators such as described in Section 3.2 may be used in the command arguments. Two of the most useful of the substitution operators for this application are "@tempdir@" and "@node@". The @tempdir@ operator is replaced by the actual name of the temporary directory where the DOOR.SYS file is written. The directory name includes the device name and ends with a backslash. So, for example, if a user had ID number 43, the @tempdir@ operator would be replaced by "C:\BBSTEMP\TMP43\". Note, the "C:\BBSTEMP\" portion of this specification is set using the SYSOP program. The @node@ operator is replaced by the line number. So if a user was running on line 4, the @node@ operator would be replaced by "4". Another potentially useful substitution operator is @userid@ which inserts a BBS identification number that is unique for each user. Chapter 14. Door Programs 137 The temporary directory for the user has this number as the last part of its subdirectory name. For example, the following example executes a door command file named "c:\chess\chess.cmd" and passes the line number and temporary file directory as arguments: $item key=C action=door("c:\chess\chess.cmd @node@ @tempdir@") The commands that should be placed in the batch file to start the door program will vary depending on the needs of the door. Usually, the command file should begin with a "CD" command to set the directory where the door program is stored as the current directory. Following this there may be other setup commands and then the actual command to run the door program. If you pass arguments to the batch file you should use %1, %2, etc. to insert them into DOS style BAT files or 'P1', 'P2', etc. to insert them into TSX style CMD files. The following is an example of a TSX CHESS.CMD file to start a chess program. cd \chess pchess /S 'p1'door.sys In the case of the pchess program, the "/S" argument tells it to use a DOOR.SYS style drop file. The second argument, "'p1'door.sys", is the file specification for the drop file. The 'p1' parameter insertion operator is replaced by the first argument passed to the command file. In this example it would be appropriate to use the @tempdir@ substitution operator for the first argument to cause the name of the temporary directory where DOOR.SYS is stored to be passed as the argument. Remember, @tempdir@ produces a full directory specification including a trailing backslash; so, when 'p1' is inserted in the string 'p1'door.sys you end up with a full file specification such as "c:\bbstemp\tmp43\door.sys". An example of a menu item line to start this command file is shown below. $item key=C action=door(\cs\chess.cmd @tempdir@,Starting Chess) The second argument to the door action, "Starting Chess", is displayed inside a box while the chess program is getting started. While running a door program, all output that the program directs to COM 1 is sent to the user's terminal. Output generated by the door program that would normally appear on the console screen is discarded. This can make it tricky to debug the batch files that start door programs. The best way to monitor what happens when a door batch file runs is to use the TSX "log file" facility. This causes output generated in the batch file that would normally be displayed on the console to be written to a disk log file. To do this place a command of the following form near the beginning of the batch file: Chapter 14. Door Programs 138 SET LOG/FILE=filename Where 'filename' is the name of the log file to be created. This command should be placed after the "CD" command that selects the current directory or you can specify a directory as part of the file name. At the end of the batch file add the following command to close the log file: SET LOG/CLOSE Once you have added these commands, you can run the door and then examine the log file to see if the door program generated any messages. The following is an example of a complete command file with log file commands: cd \chess set log/file=chess.log pchess /S 'p1'door.sys set log/close 14.5 Taming Door Programs Most door programs are written to run in the single-user DOS environment. Because of this, they typically execute an idle loop while waiting for commands to be typed by the user. This loop consumes CPU time and may bog down the operation of other users. (Note: "native" TSX-BBS routines never loop while waiting for commands, they pause execution so that other users can run.) To minimize the effect of idle looping, you can use the TSX PMAN program to set program attributes so that TSX will reduce the priority of these programs while they are idle. The TSX-32 User's Manual fully explains the PMAN command but we will summarize the basic information you need here. Start PMAN by typing the TSX command "PMAN". The initial screen is a list of the currently installed programs. Type 'A' to select the "Add entry" action. Enter the full specification of the executable program file in the "Program specification" field at the top of the screen. This specification should include the device, directory, file name, and extension (for example, "C:\CHESS\PCHESS.EXE"). Next, press Page-down and locate the field named "IDLETIME" at the bottom of the screen. The idle time parameter controls how long TSX will allow the program to execute at normal priority between times when it sends or received characters through the controlling serial line. The value is specified in units of hundredths of seconds, so a value of 200 corresponds to 2 seconds. The appropriate value to specify depends on door -- a chess program that computes for a significant time each time a command is entered will need a larger value than a game that performs some simple action for each command. If you specify too large a value then the door program will be allowed to run at the normal priority for longer than necessary causing an increased impact on other users. If you specify too small a value then the door may not finish the Chapter 14. Door Programs 139 computing needed to satisfy a command before its priority is reduced resulting is slow or choppy responses to its commands. A reasonable value to use as an initial value for IDLETIME is 200 (2 seconds). You can then experiment with running the door and increase or decrease the value as appropriate. Once you have set the IDLETIME value, press ESC twice to exit from the PMAN program. Program attributes set using PMAN are retained across system restarts. Chapter 15 The SYSOP Program Operation and maintenance of the TSX-BBS is easy, even for people who do not have much experience with computers. This is because TSX-BBS includes an on-line guide, the SYSOP program, which presents step by step instructions using menus and field entry screens. Because basic system management is either done automatically by the BBS, or conveniently using the high level SYSOP tool, managers of TSX-BBS boards do not need to learn how to edit complex and cryptic control files to maintain and customize their systems. To run the SYSOP program, simply type the command SYSOP. SYSOP is menu driven; pressing either ESC or X (for eXit) from the main menu will exit the SYSOP program. Many of the system configuration options you set using the SYSOP program are stored in the board configuration file CONFIG.BBS. This includes color selections, chat groups, mail routes, general settings, QWK configuration, utility scheduling, and more. SYSOP remembers all the changes you make and writes out an updated copy of CONFIG.BBS (if you make any changes at all) when you exit the program. Because of the way SYSOP remembers and stores configuration information, SYSOP will not permit two system operators to simultaneously make such configuration changes. However, since other functions (such as the current system status display, known as the dashboard) are also accessible from the SYSOP program, more than one SYSOP is allowed to be in the SYSOP program simultaneously. Should another system operator be running SYSOP when you start the program, you will receive the message: +------------------------------------+ | Configuration is locked by another | | sysop, other functions available | +---- Press any key to continue -----+ The following sections discuss each SYSOP function in detail. 15.1 General Setup Miscellaneous BBS configuration parameters are entered using the general set up screen, shown below. An explanation of each of the fields follows. 140 Chapter 15. The SYSOP Program 141 +------------------ TSX Sysop Management Utility ------------------+ |##################################################################| |#+----------------- General Setup Parameters -----------------+###| |#| |###| |#| BBS name: __________________________________ |###| |#| Location: __________________________________ |###| |#| Phone number: ________________________ |###| |#| QWK ID: _________ |###| |#| Sysop 1 name: _____________________________ |###| |#| Sysop 2 name: _____________________________ |###| |#| Sysop 3 name: _____________________________ |###| |#| Inactivity limit: 0________ |###| |#| Allow handles: N |###| |#| Callback verification: N |###| |#| |###| |#| |###| |#+-------------------- ESC=Save, F4=Abort --------------------+###| |##################################################################| +------------------------------------------------------------------+ BBS Name should be filled in with the name of your board. This board identification can then be included in screens wherever appropriate. The @bbsname@ construct expands to the name you put in this field. For example, the standard GOODBYE phrase, used by LOGON.TPL when a user logs off (if no goodbye file exists), thanks the user for calling @bbsname@. Location should be filled in with your location (e.g., Dallas Texas). It can retrieved for screens using the @location@ construct. Phone number is the primary phone number for your board. QWK ID is the short BBS ID code which is included in downloaded QWK packets. Note that QWK packets also include the BBS name. Sysop 1 through Sysop 3 are expanded by the constructs @sysop1@, @sysop2", and @sysop3@ constructs. Additionally, the first sysop listed is the person who receives mail when a user asks to send a mail message to the sysop. The inactivity limit field is used to log users off after they are inactive for a period of time. This feature prevents users from tying up phone lines which they are not actually using. The value specifies how many minutes of inactivity a user is permitted before being forced off. Note that users receive one warning message before the logoff occurs. To specify that users can remain inactive for an indefinite period of time, specify 0 for the inactivity limit. The allow handles field is a yes/no field which specifies whether users can select handles, or alias names, for the purposes of electronic mail messages and chat groups. Chapter 15. The SYSOP Program 142 Callback verification is a yes/no field which specifies whether you want the LOGON.TPL program to perform callback verification for new users. Callback verification is described in Chapter 6.2, page 63. 15.2 User Authorization Most sysops do not want to give all callers to the bulletin board equal, unrestricted access. Although you can easily configure the system for such an open door policy, TSX-BBS incorporates numerous features designed to identify users, and define different user classes with different access privileges. At the center of these features is the User Authorization File (UAF), often referred to as the "Userlog". This section provides an overview of how the TSX-BBS security system works, and explains how to manage user authorization records using the SYSOP program. In order to be granted access to the board, users must log in providing a first and last name. Even if you wanted to grant all callers equal access, the system must log users in because it maintains critical information for them in the UAF including their terminal configuration, message counts, and form selections. User data is stored in a disk file called UAF.BBS. While the system is running, a daemon process called the Name Server coordinates access to the UAF, providing information needed about users while they are on the board, storing updated information about them, and communicating with the system manager about new accounts. Because the name server utilizes the advanced virtual memory management of the TSX-32 platform to maintain recently accessed information and provide immediate access to the data in the user file, it is practical to run a system with many thousands of authorized users without compromising system performance. As we will see, the UAF organizes the critical privileges associated with user records into user classes, making it convenient for the SYSOP to specify the access for new users, paying customers, expired accounts, or any other classes which you decide are meaningful for your installation. Furthermore, each user can have individual privileges (whose meaning are defined by you) to allow you complete flexibility in tailoring access for individual BBS users. UAF management is accessed from the SYSOP main menu by typing 'U' to select "User authorization". When you do, you be presented with a browse screen showing the currently authorized users. The first time you select the user browse screen, it will be blank because nobody has been authorized to use your board. After a few users are authorized, the screen will look like this: Chapter 15. The SYSOP Program 143 +------------------ TSX Sysop Management Utility ---------------+ |###############################################################| |##+------------ Users ------------+##+---- Action keys -----+##| |##| Cappannari, Dan |##| Enter = Edit |##| |##| Clown, Binky |##| A = Add |##| |##| Mott, John |##| C = Class |##| |##| Sherrod, Phil |##| D = Delete |##| |##| |##| F = Find |##| |##| |##| M = Modify |##| |##| |##| P = Privileges |##| |##| |##| U = User classes |##| |##| |##| X = Exit |##| |##| |##+----------------------+##| |##| |############################| |##+-------------------------------+############################| |###############################################################| +---------------------------------------------------------------+ This is the user browse screen used to access all the SYSOP user authorization functions. The action keys on the right show the available functions. A highlight bar shows which user is currently selected. Functions such as modify or delete operate on the currently selected user, while others such as privileges and user classes apply to user authorization as a whole. In the sections that follow we will describe adding, deleting, and modifying user records. Then, we will introduce user classes and privileges. 15.2.1 Adding New Users It is not necessary for you to add a new user to the UAF before he can get on to your board. Normally, people who are not yet authorized to use the system are permitted to register themselves as new users, and are granted the access restrictions you specify for the user class named BASIC (user classes will be explained shortly). Later, you may elect to upgrade this user to a more advanced class (for example, when he pays an access fee). However, you may directly enter new users into the UAF yourself, specifying any access levels you wish. To do this, first access the user browse screen by selecting User authorization from the main SYSOP menu. You want to add a new user so you type the letter 'A' for Add (no Enter key is needed). Doing so will place you in the first page of the multi page user information screen used to enter and modify user authorization records. This will appear similar to the figure below (although some fields are omitted from the figure for sake of brevity): Chapter 15. The SYSOP Program 144 +----------------- TSX Sysop Management Utility -------------------+ |#+------------------- Authorization Record ---------------------+#| |#| First name: _____________ Expires: ________ |#| |#| Last name: _____________ ANSI: _ |#| |#| Password: _____________ Color: _ |#| |#| Birthdate: _____ IBM characters: _ |#| |#| Chat handle: _____________ Protocol: _______ * |#| |#| Address 1: _______________ Security: ___ |#| |#| Address 2: _______________ Status: _ * |#| |#| City: _______________ Language: ________ * |#| |#| State: _______________ Scroll: _ |#| |#| Data #: _______________ Called back: _ |#| |#| User class: __________________ |#| |#| Credit card #: __________________ |#| |#| type: _______ |#| |#| expires: _____ |#| |#| Comment 1: ____________________________________________ |#| |#| Comment 2: ____________________________________________ v#| |#+----------- F1=Help, F4=Quit, ESC=Save --------- Page 1 of 3 -+#| +------------------------------------------------------------------+ Fill in the demographic information (such as name, address, and phone number) for the new user. While in the field editor, the ENTER key is used to move to the next field. Up and down arrows move between fields, while right and left arrows move within the current field. Other within field keys such as insert, delete, home, and end are also supported. The page up and page down keys are used to move between the multiple pages of the user record. You will probably not want to fill in fields which provide access restrictions, such as privileges, message limit, daily time limit, and so forth. These fields will be filled in for you when you select a class for the new user, which will be described below. Some of the fields in the user record, such as the date the user last logged into the board, are for your information only, and can not be modified by you. Field entry screens in SYSOP always provide instructions for leaving the screen on the bottom border. You may press ESC to save the new record or F4 to discard it. If you press ESC, you will be returned to the user browse, which will now include the newly authorized user. 15.2.2 Modifying Users To modify or view information for an existing user, simply highlight the user (you can either use page up, page down, home, end, and arrow keys to move the highlight bar or you can type 'F' for the find function and move directly to the user) and press 'M' for modify. The user information screen will appear with current settings for the user filled in. After you make the desired changes, press ESC to save them or F4 if you need to discard them. Chapter 15. The SYSOP Program 145 15.2.3 Removing Users Although TSX-BBS allows user accounts to expire, and provides automatic access restrictions for expired accounts, you will want to periodically purge the UAF of old records. To remove a user from the user authorization file, highlight the user as described above and press 'D' for delete. You will be asked to confirm the deletion of the user. Once you confirm by typing 'Y', the user record will be irretrievably deleted. 15.2.4 User Classes and Privileges Some of the fields in the user information screen define the privileges and levels of access which the user has to your board. Although you can set each of these fields on an individual user basis, this can become tedious. To simplify management of these various access levels, TSX-BBS provides "user classes". Each user class has a name and an associated set of privileges and access limits. In one operation, you can assign a class to a user. This has the effect of changing all of the user's privileges and limits to match those specified for the class. This makes it easy to upgrade users as they register or downgrade them as they expire. Class assignments take place in two ways: you (the sysop) can assign a class to a user at any time. The class can be assigned by using the SYSOP program. You just select a user and indicate which class to assign. The second type of class assignment is performed automatically by TSX-BBS when some event occurs. For example, when a new user first logs on and enters basic information that user is initially assigned the BASIC class. Typically, the sysop defines BASIC class to provide limited access to the system. If callback verification is used, the user's class is changed to VERIFIED once the callback verification is successfully completed. If you assign an expiration date to a user and the date passes, the user is assigned the EXPIRED class. TSX-BBS comes with the following predefined classes. You are welcome to define new classes and modify the privileges and limits associated with these classes. BASIC -- This class is assigned to new users once they enter basic information including their name, address, and phone numbers. VERIFIED -- This class is assigned to a user who successfully completes callback verification. REGISTERED -- This class is available for the sysop to manually assigned to users who send in registrations. TSX-BBS never assigns this class on an automatic basis. EXPIRED -- If a user has an expiration date, this class is assigned to the user the first time the user logs on after the expiration date. Chapter 15. The SYSOP Program 146 Once you install TSX-BBS, you are welcome to customize the built-in classes which come with the board and define new user classes. For example, you may want to define a class named GOLD to provide extra access levels to users who pay a premium subscription fee. However, be aware that the BASIC, VERIFIED, and EXPIRED classes are used by the standard LOGON and CALLBACK programs. Adding, modifying, and deleting user classes is similar to managing individual user records. From the user browse screen, select 'U' for User classes and you will be placed in a second user class browse screen similar to the one depicted below: +------------------ TSX Sysop Management Utility --------------+ |##############################################################| |##+---------- User Classes ----------+#+- Action keys --+#####| |##| Basic |#| Enter = Edit |#####| |##| Registered |#| A = Add |#####| |##| Expired |#| D = Delete |#####| |##| |#| M = Modify |#####| |##| |#| X = Exit |#####| |##| |#+----------------+#####| |##| |########################| |##+----------------------------------+########################| |##############################################################| +--------------------------------------------------------------+ New classes are created by typing 'A' for add. Much like the user browse, the highlight bar selects which class is acted upon by the delete and modify functions. Entry and modification of user classes is done using a field edit screen which looks like this: +------------------ TSX Sysop Management Utility ------------------+ |#+------------------- User Class Description -------------------+#| |#| Class name: Basic_______________________ |#| |#| Minutes per day allowed: _________ |#| |#| Daily download byte limit: _________ |#| |#| Security level: 33_______ |#| |#| Messages stored: 100______ |#| |#| |#| |#| Built in privileges Sysop defined privileges |#| |#| ---------------------------- ------------------------ |#| |#| P00 Forum: Y S00 Adult: N |#| |#| P01 Mail: Y S01 Corporate Forum: N |#| |#| P02 Download: N S02 XYZ Corp Files: N |#| |#| P03 Upload: N |#| |#| P04 Vote: N |#| |#| P05 Drop to TSX: N |#| |#| P06 File library N |#| |#| |#| |#+--------------------- F4=Quit, ESC=Save ----------------------+#| +------------------------------------------------------------------+ The first fields on this screen provide various access level restrictions. These include the total number of minutes per day the user is allowed on the board, the total number of bytes per day Chapter 15. The SYSOP Program 147 the user is allowed to download, and the total number of messages the user is allowed to store in the message filing cabinet. The security level is a numeric value which can be tested using the PRIVLEV system variable in conditional expressions. For example, you may designate that only users with security level 7000 or higher are given access to the corporate data file area by using a privilege expression of the form "PRIVLEV>=7000". The remainder of the user class definition consists of two sets of privileges: those which are built-in and used internally by TSX-BBS, and those which you have defined yourself for customized access control. The built-in privileges have obvious meanings. For example, in order for a user to be able to access any mail function, he must have mail privilege. Sysop defined privileges can be used whenever a privilege expression is permitted to control access to a system component. For example, a privilege expression can control whether a user is permitted access to a specific file library. You may designate sysop privilege S01 as ADULT and restrict access to the adult file library by specifying "S01" as the access expression. Privilege expressions are complete logical expressions, so that you can require combinations of privileges (as in "S01&&S02") or any of a set of privileges (as in "S01||S02") for access control. Privilege access expressions can also be used to control various types of access to forums, menus, and may be used in TPL programs. See Chapter 4 for a full explanation of privilege expressions. You create sysop defined privileges from the main user browse screen by typing 'P' for privileges. You will be placed in a screen that allows you to specify the names for up to 80 privileges with labels S00 through S79. All the privileges for which you specify names are included automatically in the user class definition screen. Once you have defined privileges, they will also appear in the user information screen for individual users. Once a user class is defined, the class may be assigned to a user. To do this, highlight the user in the user browse and type 'C' for Class. You must then choose a class from a pop-up menu listing of all the currently defined user classes. When you assign a new class to a user, it has the effect of "stamping" that user record with all the access controls which are defined for the new user class. Suppose that you have defined a class named STUDENT which permits one hour of connect time and forum privilege, denies chat privilege, but does not specify anything else (all other fields in the class description are left blank). If you assign STUDENT class to a user, the connect time limit will be set to 60 minutes, forum privilege will be granted, chat privilege will be denied, but all other fields of the user's record will be left untouched. Chapter 15. The SYSOP Program 148 15.3 Scheduling Utilities 15.3.1 Introduction Because TSX-BBS runs under the TSX-32 multi-user operating system, it is never necessary to take the board down to perform regular file maintenance such as squeezing the mail database or cleaning old messages out of forums. Software components like the mail and forum system were designed so that these maintenance procedures can be active at the same time that users access the databases. TSX-BBS comes with file maintenance programs that periodically run as background "daemons" or "detached jobs". The sysop has control, through the utility scheduling facility of the SYSOP program, of how often (and at what time) these background daemons run. This section discusses how to use this scheduling facility. Specific information about what each file maintenance program does is found in the appropriate section of the manual. For example, the mail database sweeper is documented in the chapter on the electronic mail system. In addition, a summary of the scheduled events and a description of the schedule server itself can be found in Chapter 20. A running TSX-BBS system includes a permanent detached job named the Scheduler. The scheduler is responsible for invoking the various maintenance and communication programs which need to be run on a periodic basis. When you use the SYSOP schedule facility to manage the schedules for these event, you modify a file named BBS:SCHEDULE.CTL. This file, containing the schedule control information, is read by the scheduler daemon when it starts, and re-read when you make a change. 15.3.2 What Can Be Scheduled Your TSX-BBS system comes configured with reasonable schedules built in for all the file maintenance programs which are included with the system. These include the mail sweeper and forum sweeper. If you acquire optional system components from S&H, you may be instructed to use the scheduling screens to add new file maintenance or communications programs to the system at that time. In addition, you are welcome to use the scheduling facility to schedule execution of your own programs and batch files. 15.3.3 The Schedule Browse Screen To access the schedule system, type 'S' for schedule from the SYSOP main menu. You will be placed in a browse screen showing all the currently scheduled utilities: Chapter 15. The SYSOP Program 149 +------------------ TSX Sysop Management Utility ------------------+ |##################################################################| |#+--------- Scheduled Utilities ----------+#+- Action keys --+####| |#| Forum Sweeper |#| Enter = Edit |####| |#| Mail Sweeper |#| A = Add |####| |#| |#| D = Delete |####| |#| |#| E = Edit |####| |#| |#| X = Exit |####| |#| |#+----------------+####| |#| |#######################| |#+----------------------------------------+#######################| |##################################################################| +------------------------------------------------------------------+ While in the browse screen, a highlight bar indicates which of the scheduled utilities (or events) is currently selected. You can use the arrow keys, page up, page down, home, and end to move this highlight bar. An action key box on the right indicates what keys to press for various actions. The edit and delete actions apply to the currently selected utility. When you are finished with the schedule system, press 'X' or ESC to return to the SYSOP main menu. 15.3.4 Modifying an Existing Schedule To modify an existing schedule, highlight it and press 'E' or ENTER. You will be placed in the first page of the schedule information screen: +----------------- Schedule for Forum Sweeper ------------------+ | | | Name: Forum Sweeper___________________________ | | Program: BBS:FSWEEP.CMD__________________________ | | Log file: BBS:FSWEEP.LOG__________________________ | | Tag name: FSWEEP | | | | Schedule begins on next page | | v +--------------------- ESC=Save, F4=Abort -------- Page 1 of 5 -+ The first page describes the event being scheduled. The name field specifies the title which appears on the schedule browse screen (this is used for display purposes only). The program field defines what action the Scheduler daemon will take when the time comes for the event to take place. The Scheduler can run batch files or programs. If the program field contains a filename with the extension of EXE, EXP, or COM, then this is assumed to be a program. If it contains a filename with the extension of BAT or CMD, the file is assumed to be a batch file. In the example shown above, the forum sweeper is specified in terms of a command file name, BBS:FSWEEP.CMD (the extension .cmd is the Chapter 15. The SYSOP Program 150 32-bit equivalent of a 16-bit batch file, .BAT). The Scheduler recognizes that FSWEEP is a command file (instead of an executable program) because of the .CMD extension. Each time that the program or batch file is run, a log file is left on the disk so you can be sure that it completed successfully. The log file contains the same information which would be displayed on the screen if you ran the program or batch file at the system console. The name of this log file is specified in the log file field. Each scheduled event can have a tag name associated with it. The tag name is used to ask the schedule server to invoke the specified event right now. For example, when a user sends a Fidonet crash message, the BBS engine uses the reserved tag name FIDOSCAN and asks the schedule server to start a Fidonet mail scan so the mail can be sent immediately. Subsequent screens show what times during the day you want the scheduled utility to be run. Times can be specified at 5 minute intervals. Each time field is a yes/no field; simply enter a 'Y' in the field to ask the scheduler to run the program or batch file at the indicated time. You may watch the activity of the Scheduler itself by viewing the event log BBSSCH. To do this, issue the SHOW EVENT command from the TSX-32 system prompt, highlight BBSSCH, and press ENTER. 15.3.5 Adding a New Schedule To add a new program or batch file to the list of scheduled events, type 'A' from the schedule browse screen. You will be placed in the same schedule information screen used for modifying existing schedules. Be sure that you correctly specify the name of the program or batch file. The program and log file fields should include the disk and directory name. After you have scheduled a new utility, you should wait until the first scheduled time has passed and look for the log file to be sure that the scheduler is properly invoking it. Note that TSX command procedures have many powerful features not found in standard DOS batch files. Refer to the TSX-32 or TSX-Lite documentation for full information. The HELP command also includes on-line help for command file constructs such as IF, GOTO, EXIT, CHAIN, ON, Assignments, and lexical functions. 15.3.6 Deleting a Schedule To remove a program or batch file from the list of scheduled events, highlight it in the schedule browse screen and type 'D' for delete. You will be asked for confirmation and you must type 'Y' to be certain that you want to delete the event. Chapter 15. The SYSOP Program 151 Note that deleting an event from the list of scheduled utilities does not remove the program or batch file from the hard disk; it merely removes the schedule from the schedule database. 15.4 Color Customization TSX-BBS users can separately specify whether they want ANSI escape sequences and whether they want these to include color sequences. ANSI and color are two separate options offered to the user in the on-line Configuration Options Menu and controlled by the SYSOP in the UAF. However, the user will not receive any color sequences unless ANSI is also specified. When constructing screens, TSX-BBS can be directed to include color sequences in two different ways. First, colors can be specified in terms of PC color attribute bytes. For example, the color attribute hex 01 indicates a black background and a blue foreground (a full explanation of PC attribute bytes is provided in chapter 3). However, specifying colors in terms of literal attribute values can be inconvenient, since it requires you to remember what values are used for various types of text, and requires you to keep track of what colors each value means. To make color customization easier, TSX-BBS maintains a set of colors for common uses such as menu text, hot characters, box borders, and so forth. Then, instead of referring to colors by their attribute value, you can use names such as "HOTKEY" or "MENUBOX". These rules for specifying colors in screens you design are discussed in Chapter3, Page21. These named colors are also used automatically by the various built-in functions of the BBS. For example, certain colors are designated for editor text, chat display, file library lists, and so on. TSX-BBS provides attractive default color values for each of these colors. However, you can customize the default color assignments by selecting the Colors option from the SYSOP main menu. The color manager is organized into a set of example screens, including screens from chat, the editor, the file library, and menus. This set of examples is designed to provide at least one instance of every named color used by the BBS. However, there is considerable overlap. For example, common text is shown in the color called "BASE", which appears on most of the screens shown in the color manager. When you select an example from the list provided, you will be placed in a color modification screen like the one shown below. Obviously, you must be using a color monitor when customizing system colors. Chapter 15. The SYSOP Program 152 +------------------ Menu colors -------------------++------+ | +-----------------------+ || F B | | | TSX-32 Bulletin Board | || ---- | | +-----------------------+ || X>X | | [E]lectronic mail || X X | | [D]iscussion Forums || X X | | [C]hat || >X X | | [G]oodbye || X X | | || X X | | Choice: || X X | | || X X | +-------------------- ESC=Save --------------------+| X X | +----- Use arrows to select, ENTER to modify ------+| X X | | > Base color || X X | | Hot keys || X X | | Brackets around hot characters || | | Color for menu title box lines || | | Color for text for menu title || | +-------------------- ESC=Save --------------------++------+ The upper left portion of the color customization screen depicts an example of the screen you are customizing (in this case, a menu screen). As you make changes, you will be able to immediately see their effect on this sample screen. The lower left portion of the color customization screen lists all those colors which are used by the current sample. Rather than give the mnemonics for selecting the color (such as BASE), a brief description is shown (e.g., Base color). An indicator arrow indicates which of these colors is currently being edited. Along the right margin of the color customization screen, the 16 possible foreground components and 16 possible background components of a color code attribute byte are shown. Arrows indicate the current foreground and background components of the selected color. To modify the color of a certain type of text, first use the arrow keys to select it and press ENTER. For example, if you wanted to customize the appearance of hot keys, you would press the down arrow once, moving the color selection indicator from Base color to Hot keys, then press ENTER. When you press enter, a prompt appears along the bottom margin telling you to use arrows to set the foreground and background color, and ENTER to save the current setting. To continue with our example, the default attribute used to display hot keys is a bright yellow foreground against a black background. (The corresponding attribute value is hex 0E, because black has the value of 0, and bright yellow has the value of 15, or hex E). When you select hot keys, the arrow indicators show that the current foreground selection is yellow and the background selection is black. Chapter 15. The SYSOP Program 153 Using the up and down arrows allows you alter the foreground value associated with hot keys. Press up-arrow twice and watch the hot keys shown on the screen change from bright yellow to bright cyan, then bright red. While in this color modification mode, the right and left arrow keys are used to alternate between foreground choices and background choices. Press the right arrow key and note that the blinking marker moves from the foreground component (now bright red) to the background components listed to their right (currently black). Now press the down arrow key and see the background of the hot keys change from black to blue, then green, and so forth. You can press left arrow, make further adjustments to the foreground, and right arrow to experiment with the background, changing the hot key appearance to any of 256 possible foreground/background combinations. When the appearance of hot keys is to your satisfaction, press ENTER (or ESC) to save the current setting. Note that whereas the last eight foreground colors are bright, the last eight background colors are blinking. This is an aspect of the way color attribute bytes work. After adjusting a specific type of text, you may return to the list of colors used by the current screen sample and make changes to other colors. For example, after adjusting the hot keys, you may want to make changes to the brackets around hot keys so they have the same background color. Finally, press ESC to return to the list of sample screens. From here, pressing ESC (or X for eXit) will remember the changes you have made. Note that changes are not permanently recorded on disk until you exit the SYSOP program. If you decide that you have made colors worse, not better, you may press 'Q' from the screen selection menu and discard all the changes that you have made. 15.5 Chat groups As discussed in Chapter13, the TSX-BBS Chat facility is divided into discussion groups. In order to be able to converse on-line with other users, you must first join a specific discussion group. Chat groups can be created by users who want to invoke discussions on a particular topic, such as computers. These user defined groups disappear when the last user leaves the group. You will probably find that users are more encouraged to use the chat facility if permanent discussion groups have been created by the sysop. These permanent groups give new users an idea of what discussion groups are all about, and make some suggestions for topics of discussion. In addition to topic centered discussion groups, you will probably want to create one or more general areas with names like "Chat lounge" or "Adult discussion". Definition of the permanent chat discussion groups is done by selecting the chat groups option from the SYSOP main menu. When Chapter 15. The SYSOP Program 154 you do this, you will be placed in a field entry screen used to enter or modify the list of permanent discussion groups. To add a new discussion group, simply enter its name. To remove an existing discussion group, use the DELETE key to completely erase its name. When you are finished modifying the permanent groups, you may press ESC to save the changes, which will take effect immediately. Note that if you delete a permanent group which is currently in use it will not disappear until the last member has left it. If you decide to discard the changes you have made in the chat information screen, press F4. 15.6 Paging Control TSX-BBS has the ability to allow users to "page" the sysop when they want to engage in an on-line conversation. This type of conversation is a private, real-time exchange of text between the sysop and an individual user. It is not related to the BBS "chat" facility where multiple users exchange messages. When a user pages the sysop a message appears on the console screen giving the time, the name of the user, and a message saying that the user is paging the sysop. The bell is also rung to alert the sysop to the paging request. TSX-BBS allows you to configure the paging system so that it is disabled completely, enabled, or enabled and disabled automatically based on the time of day and day of the week. To control the paging, type 'P' to select "Paging control" from the main SYSOP menu. You will then be presented with a screen that has one choice at the top and an array of day and time based choices below. The top item has three choices: "[E]nable paging until further notice", "[D]isable paging until further notice", and "[S]cheduling table controls paging". If you type 'E', paging will be enabled until you return to this menu item and make another choice. If you type 'D' paging is disabled. If you type 'S', then paging is enabled and disabled automatically based on the day and time as selected by the scheduling table. The day/time scheduling table has one entry for each hour of the day for the weekdays Monday through Friday and separate entries for Saturday and Sunday. If you set an entry to 'Y' then paging is enabled during that hour; if you set it to 'N' then paging is disabled during the hour. Paging is always disabled when the sysop is logged off and when the sysop is running a graphics mode program on the console. When you receive a paging message from a user, you can engage the user in a conversation by running the SYSOP program, selecting the "dashboard" display, highlighting the entry for the paging user Chapter 15. The SYSOP Program 155 (the user's activity will show as "Paging" in blinking red), and then typing 'C' to select the "Chat" function. Press ESC when you wish to terminate the conversation. Note that you can also initiate a sysop-to-user chat without waiting for a user to page you. The paging function is invoked by offering the users a menu choice whose action is "pagesysop". If you wish to disable paging entirely it is best to simply not offer this option on any menu. The following is the example of a menu "$item" entry to invoke paging when the letter 'S' is typed: $item key=S action=pagesysop 15.7 Handle Control A "handle" is a nickname that users may choose for themselves. Users may set handle names from the User Configuration option of the main BBS menu. TSX-BBS does not allow two users to have the same handle name. The sysop can disallow the use of handles altogether or can allow handles to be used in a limited set of circumstances. To control handle usage, select the "Handle Control" option from the main menu of the SYSOP program. You will then be presented with a list of entries. You should enter 'Y' by an entry to enable handle use or 'N' to disable handle use. If handle use is disabled, the user's real name is used for that situation. 15.8 Language files 15.8.1 Introduction Virtually all of the prompts, messages, and small menus used by ISX are stored in a database file called a "Language Definition File", or "Phrase file". There are two reasons that this data is not encoded into the programs of TSX-BBS itself. The first is for foreign language support. Storing the data in an external database allows the SYSOP to translate the text to any other language desired. In fact, each authorized user can be assigned a different language file, for a truly multi lingual board. The second reason that the text data for TSX-BBS is stored in an external database is that you may want to customize or adjust individual phrases, prompts, and menus to better match the personality of your board. There are actually two different utilities for updating the language database. One, which is built into the SYSOP control program, presents phrases one at a time for on-screen editing. This first method is discussed in this chapter. Chapter 15. The SYSOP Program 156 You should be aware that there is a second method which some SYSOPs may find better suited to complete translation from one language to another. Registered users may download the ASCII source of the entire language database, along with a program which will generate the database from the source file. This allows you to use your favorite editor and other utilities to aid in the translation process. For more information about the external source file approach, contact S&H. Adjustments to individual phrases and menus is easily accomplished using the "Language File" function of the SYSOP program. When using SYSOP to edit a language database, the entire file will be read into memory, updated, and rewritten. 15.8.2 Creating New Databases After you select language files from the main menu, the SYSOP program presents you with a browse list of all the languages currently defined for your board (it does this by looking for all the files in the ISX directory with the extension .LDF). Each of the files listed in this screen is a phrase file database for a different language. ISX is shipped with the database for english, ENGLISH.LDF. To create a new language file, use the Create option in the SYSOP language browse screen. You will be provided with a data entry screen similar to the following: +-------- Specify characteristics for new language file ---------+ | Name of language file: ________ | | Name of file to copy: ________ | | Note about new file: ___________________________________ | +---------------------- ESC=Exit, F4=Abort ----------------------+ The name you specify is the name of the .LDF file you wish to create. You should give a name which describes the language, such as GERMAN or SPANISH. If you specify a file to copy, an existing language file is copied as a template. You will then translate each phrase from the template language to the new language. Specifying a file to copy is highly recommended, since otherwise you would have to re-enter every phrase by hand. The note you enter to describe the new file will appear in the language browse list, and is for your own clarification only. 15.8.3 Assigning Languages to Users Using the user information screen, you assign each BBS user one of the available languages. A pop-up menu in the user screen will allow you to select from existing language files. By assigning a different phrase file to each authorized user, ISX can thus present phrases, prompts, and menus in the each user's native language. Chapter 15. The SYSOP Program 157 15.8.4 Editing Phrase Entries After you create a new language database, or to simply customize the text in an existing one, you must access and edit individual phrase entries, one at a time. Each phrase entry corresponds to a prompt, phrase, or "mini-menu" provided by TSX-BBS. Note that you may add additional entries to the database and retrieve them in your own TPL programs as well. To edit an individual entry, select the phrase file you wish to modify and type M or Enter. This places you in a browse list of all the individual phrases and menus in the file. This phrase browse screen will have the language being browsed shown at the top border. In the phrase browse you will use the arrow keys to select the entry you want to modify and press ENTER to edit it. The data entry screen for modifying an individual phrase looks similar to this: +-----------------------------------------------------------------+ | Text displayed to user | | Password: ____________________________________________________ | | ______________________________________________________________ | | ______________________________________________________________ | | | | Purpose of text | | Used to prompt a user for his password._______________________ | | ______________________________________________________________ | | ______________________________________________________________ | | | | Mnemonic used by TPL: PASSWORD | | Brief description: Prompt for password_______________ | | | +------------------------ ESC=Exit, F4=Abort ---------------------+ The first section of the data entry screen contains the text which is displayed to the user when the phrase or menu is used by the system. In the example shown, the phrase is used to prompt the user for a password. The second section, labelled "Purpose of text", is only used for the benefit of the sysop who must maintain the text database. If you are translating the text database to a different language, you are welcome to translate this text as well (for the benefit of SYSOPs who speak the language), but this text is never displayed to a BBS user. You may want to use this field to place notes to yourself regarding use of the phrase. The third field, labelled "Mnemonic used by TPL", should not be altered. This field is used to generate a TPL header file which can be used by TPL and C programs to symbolically access the phrase. Chapter 15. The SYSOP Program 158 The "Brief description" field is the one line description which shows on the browse list used to select individual phrases for editing. Again, this text is only for the benefit of the SYSOP. Once you have completed your changes to the phrase, press ESC to save the changes or F4 to discard them. Note that while you edit individual phrases, the entire phrase database is only being modified in memory. Only when you return to the phrase browse screen and type X (or ESC) to save those changes is the entire phrase file rewritten to disk. You may alter several phrases and still discard all changes by exiting the phrase browse by typing Q for quit. 15.8.5 Mini Menus As we mentioned, many of the entries in a language database provide the text for a "mini-menu". Mini menus are generally one or two line lists of choices given when browsing files, e-mail, messages in forums, and so on. As an example, look at the full text of the mini menu used for the file library browse: N=D,P=U,Q=1,T=2,J=3,U=4,E=5,S=6,D=7 `Next `Prev `Jump `Search `Extra `Tag `Upload `Down `Quit: The first line of a mini menu must tell TSX-BBS what result codes are assigned to each key which the user can press. Most of these codes are numeric values which are expected by the BBS engine when it invokes the mini menu. In the example shown, the engine will perform a file upload operation if the returned code from the mini menu is 4, or quit the file browse if the value is 1. These code values are required by the BBS engine and you should not change them. Note that the special code values D and U stand for down and up. They tell the engine that the user does not want to make any choice yet, but wants to move up or down in the list of items (in this case, files) being browsed. After the first line of a mini-menu, all subsequent lines provide the text which is displayed to the user. The accent character is used to denote the "hot keys" which should be highlighted and in braces to tell the user what letters to type for each selection. When you translate a mini menu to a different language, keep the following rules in mind: . Be sure to provide the user a way to make all the selections which were possible in the original menu. . Be sure that each option in the list of choices has a unique hot key. . Be sure that the hot key letters correspond to the return values the same way they did in the original menu. Chapter 15. The SYSOP Program 159 Suppose, continuing with our example, that you are translating this menu to french, and decide to translate "Search" to "Chercher". After making this first change, the adjusted menu looks like this: N=D,P=U,Q=1,T=2,J=3,U=4,E=5,C=6,D=7 `Next `Prev `Jump `Chercher `Extra `Tag `Upload `Down `Quit: Note that even after the translation, the return value of 6 still means "Search for a file", but the prompt reads "Chercher", and the hot key which invokes the return value 6 is now C instead of S. If you have difficulty finding a translation which gives every word a unique first letter, simply change the hot key to be some other letter in the word. If you decided to translate "Next" to "Contigu", you could not re-use C because it is already used for "Chercher", so you might decide to use the N in Contigu as a hot key: N=D,P=U,Q=1,T=2,J=3,U=4,E=5,C=6,D=7 Co`ntigu `Prev `Jump `Chercher `Extra `Tag `Upload `Down `Quit: 15.9 Mail Configuration The SYSOP program is used to set up message bases for each supported mail route, and to enter specific configuration information to describe routes like Fidonet and Usenet. To access the mail configuration menu, type 'M' for "Mail Configuration" at the main SYSOP menu. The mail configuration menu has one option for setting up message bases and one option for each supported message route such as Fidonet and Usenet. Each of these options is now considered in turn. 15.9.1 Managing message bases To manage the message bases, type 'M' from the mail configuration menu to select "Message bases". You will be placed in a field entry screen similar to the one shown below: +------------------ Mail Route Configuration ------------------+ | Name ID Database Area Access | | -------------------- -- -------- ----- ---------------- | | Local mail__________ L INMAIL__ 1____ ________________ | | Fidonet_____________ F FIDO____ 3____ P12_____________ | | Usenet______________ U USENET__ 4____ ________________ | | ____________________ _ ________ _____ ________________ | | ____________________ _ ________ _____ ________________ | | | +---------------- F1=Help, ESC=Save, F4=Abort -----------------+ Each message base is defined by its name, a single ID letter, a database name, an area number, and an optional access control expression. Pop-up help for each field is available by typing F1. Chapter 15. The SYSOP Program 160 After you set up a message base for a route, users will be able to send messages via that route. If more than one route is defined (only local mail is automatically defined when you install TSX-BBS), users must select the message route from a menu each time they send an e-mail message. The name you specify in the message base field entry screen is the name they will see in this route selection menu. The ID letter you define is the character they will type to select that route. The database name you specify is used to create a pair of files to hold the message base. In the example shown, local mail is held in a message base comprised of the files INMAIL.MLD and INMAIL.MLC. Area numbers are assigned by S&H since the TSX-BBS software finds a message base by using the area number. The following area numbers are currently assigned: . 1 -- Local mail. . 2 -- Internet mail. . 3 -- Fidonet. . 4 -- Usenet. Note that defining message bases in the data entry screen does not actually create the files. Message base files are created by the BBS engine the first time they are needed. 15.9.2 Specifying Fidonet configuration Fidonet configuration is discussed in the chapter on Fidonet, in section 19.4. 15.9.3 Specifying Usenset configuration To enter the Usenet configuration screen, type 'U' for "Usenet" from the mail configuration menu. This will place you in a data entry screen used to specify various Usenet setup parameters. Each field, which is described fully in the Chapter 18, has a pop-up help menu which you view by pressing the F1 key while in that field. You may save your changes with ESC or cancel them with F4. 15.10 Discussion Forum Setup and Control The SYSOP program is used to manage forums. Many of the concepts mentioned here are described in Chapter 9. An understanding of those concepts is essential in order to effectively use the SYSOP program. From the various menus in the SYSOP program you can Chapter 15. The SYSOP Program 161 . Create a forum. Forums can be created in one of two ways: A forum can be created by name, or an ascii file can be used to import a set of names to be created. . Set access privileges for a forum. . Enable or disable autoadd privileges. . Delete a single forum or a category of forums or all forums. Forums can be deleted individually, hierarchically (delete all forums under a specified name), or deleted by specifying an ASCII file which contains a list of forums to be deleted. . Erase all the messages in a single forum or in a category of forums. . Enable or disable log files or event log display. . Specify defaults for new forum creation. . Specify locations for forum control files. . Generate a list of current forums into an ascii file. . Regenerate user index files. . Rebuild the forum control file. The forums can be accessed in one of several ways, including . A hierarchical list. . An alphabetic list. . A list derived by searching for a name component. . By forum name. . By forum number. The main forum menu is selected from the main SYSOP menu by typing 'O'. 15.10.1 Defining the Locations of Forum Control Files Before creating any forums the locations of the control files must be specified. The default location of these files is "BBS:\FORUM\". If there are a small number of forums or there is not much anticipated space required for forums this should suffice. From the main menu type 'H' to select "Housekeeping". Then type 'O' for "Organization of forums". This will display the current default and a set of lines which allow the sysop to select the base directory of a range of forums. Chapter 15. The SYSOP Program 162 In addition to changing the default location, forums can be split into up to 64 different directories according to the forum number. Each base directory can hold up to 1000 forums. It is not necessary to specify a directory for each range of forums. Wherever the directory is blank it will pick up the default value specified at the top. 15.10.2 The Hierarchical, Alphabetic, and Search displays There are several ways to view and manage the set of forums. Each of these display methods allows for various operations once a list of forums is displayed. These menus and how to navigate within them are discussed here, and then referred to when describing the various functions. From the main forum typing 'M' will select the "Modify and display" submenu. From this menu there are three ways that the list of forums can be displayed: hierarchically (type 'H'), alphabetically (type 'A'), and via a keyword search (type 'S'). Each of the menus has a list of items which is appropriate to the type of display. On each screen 'N' will advance to the next page and 'P' will go to the previous page. In each screen there are a set of action keys whose values and meaning are specified to the right of the display. Each will be discussed in discussing the display type. In order to perform a function specified by the action keys one entry must be highlighted. Typing the action key will then perform the specified action. The first entry on the screen is highlighted when the screens are entered or when a new page is selected. The up and down arrow keys go up and down within the screen, moving the highlighted bar and changing the selected item. 15.10.2.1 The Hierarchical Display Typing 'H' from the "Modify and display" menu selects the hierarchical display. Forum names have a hierarchical structure. At the topmost level there is the grand division such as "usenet" and "fido", which is discussed in Section 9.5. At levels under that there may be other levels which may contain other levels. The name "usenet.alt.cooking.chili", for instance, has 4 levels, one for each name component. Viewing the list of forums via the hierarchical display is akin to taking a directory under DOS: it only shows the entries at the current level. Under DOS you must use the "cd" command to go "up" or "down"; in this display you use "G" or the right arrow key to go down to the next lower level and "U" or the left arrow key to go up the the next higher level. In our example "usenet" is the only item at the top level. In order to perform a function on an item it must be selected. Items are selected using the arrow keys. When a screen first displays, Chapter 15. The SYSOP Program 163 or when next or previous pages are selected via 'N' or 'P', respectively, the first item is selected. An item is highlighted when it is selected. If "usenet" is the only item it is already selected so we can choose an action from the "Action keys" menu at the right. If we select 'G' to go to the next level the screen will display the single item "alt", since "alt" is the level below "usenet". If there were additional forums below the "usenet" grand division, all of the second level names would be displayed here. We can type 'G' again and see the single item 'cooking'. Typing 'G' one last time and we see the item "chili". This entry has a forum number and message count displayed with it indicating that it is a forum containing messages. In DOS you can have directories and non-directories at the same level. In a like manner, there can be forum and non-forum names at the same level. The name "usenet" by itself is not a forum but is a valid non-forum name analogous to a directory. If there was a forum at the same level as "usenet" its display would look slightly different. The forum number would display and the current number of messages in the forum would display as well. It is not unusual for there to be forums and non-forums at the same level with usenet newsgroups. The following action keys apply to the hierarchical display: 'G' -- "Go into forum". If there are name components beneath the current name this will display a screen with all the names at that level. If there are no names beneath the current one it does nothing. 'H' -- "Higher level". This will display the names above the current level. If there are no names above the current one it does nothing. 'A' -- "Add forum". This will bring up the "Create new forum" screen and allow a forum to be created at the current level. The "Create new forum" screen is discussed in Section 15.10.3. 'D' -- "Delete forum". This will allow deletion of the selected forum. If the name selected has forums beneath it it will delete those as well. This is called a "recursive" operation. The implications are that if you delete the names at the topmost level you will delete all the forums in the system. This option should be used with care. The number of forums beneath the current forum are counted and you will be prompted to confirm the request. 'M' -- "Modify forum". This allows modification of the privilege and options for the name component through the "Inspect forum" screen. This screen is discussed in Section 15.10.4. Chapter 15. The SYSOP Program 164 'I' -- "Initialize forum". To initialize a forum means to delete all its messages and reset the message counter to 1. The forum itself is not deleted, however. Choosing this action this will initialize the selected forum. If there are forums under the selected one they will be initialized as well. This is called a "recursive" operation. The implications are that if you initialize the names at the topmost level you will initialize all the forums in the system. This option should be used with care. The number of forums beneath the current forum are counted and you will be prompted to confirm the request. 'N' -- "Next page". This will advance to the next page of items at this level, if there are any. 'P' -- "Prev page". This will go to the previous page of items at this level, if there are any. 'X' -- "Exit". This will exit this display, no matter what the current nesting level is. The main advantage of the hierarchical display is the ability to get a better sense of the overall organization of the forum names and also the ability to modify a name component which is not a forum. 15.10.2.2 The Alphabetic and Search Displays The Alphabetic display and the Search display are identical in terms of functionality and display. They both show the selected forums in alphabetical order. The only difference is how they select forums for display. Typing 'A' from the "Modify and display" menu selects the Alphabetic display. After typing 'A' there is a prompt which asks for a prefix. This is just the first part of the name to subset by and provides an easy means to examine a subset of the forums which all start with a certain string. Just typing return will result in all the forums being selected. For example, if you were supporting Usenet and Fido forums and wanted to work on only the Fido forums, you could enter "usenet" when prompted for the prefix. Typing 'S' from the "Modify and display" menu selects the Search display. After typing 'S' there is a prompt which asks for a search string. This is a string which will be compared with all forum names. Those which contain the string will be selected for display Typing return will terminate the display. The distinction between selecting a prefix and specifying a search string is that the prefix must match only the first part of the name. A prefix of "usenet" would match "usenet.alt.cooking" but would not match the string "fido.culture.usenet". A search string of "usenet" would match both "usenet.alt.cooking" and "fido.culture.usenet". Chapter 15. The SYSOP Program 165 These will display all the selected forums on the system in alphabetical order. The action keys on these menues are: 'N' -- "Next page". This will advance to the next page of items at this level, if there are any. 'P' -- "Prev page". This will go to the previous page of items at this level, if there are any. 'X' -- "Exit". This will exit this display, no matter what the current nesting level is. 'A' -- "Add forum". This will bring up the "Create new forum" screen and allow a forum to be created. The "Create new forum" screen is discussed in Section 15.10.3. 'D' -- "Delete forum". This will allow deletion of the selected forum. You will be prompted for confirmation of this request. 'M' -- "Modify forum". This allows modification of the privilege and autoadd options for the forum through the "Inspect forum" screen. This screen is discussed in Section 15.10.4. 'I' -- "Initialize forum". To initialize a forum means to delete all its messages and reset the message counter to 1. The forum itself is not deleted, however. Choosing this action this will initialize the selected forum. You will be prompted for confirmation of this request. Unlike the hierarchical display, all the items display in the Alphabetical and Search lists are forums, so all the items will display a forum number and a number of messages. 15.10.3 Creating New Forums New forums can be created in one of three ways. In two of the cases the same screen is used to define a forum: "Create new forum". When the "Create new forum" screen is used to create a forum only the forum name is required. Fill in the complete name including the grand division such as "usenet" or "fido"; use periods to separate name components. Spaces within the name are not allowed but most other punctuation characters such as dashes and underlines are allowed. The use of the comment field is optional. Its value is only displayed within the SYSOP program. If desired, privilege and autoadd information may be specified at this time or may be modified later. If you specify a complex name, one involving several name components separated by periods, the SYSOP program will create entries for each part of the name. Privilege Chapter 15. The SYSOP Program 166 information will be null and autoadd will be set to 'Y' on the other name components. Privilege strings are specified as the read, write, and control privilege. The privilege expressions are evaluated at the time they are needed. For example, when displaying the list of forums to a user the read privilege is used to determine whether to include a forum or not. When a user tries to post to a forum, either interactively or through QWK, the write privilege expression is evaluated. The control privilege is evaluate when a user attempts to delete a message. See Chapter 4 for information about how to specify privilege expressions. The number of days until expiration is how many days messages are allowed to remain in the forum until the sweeper deletes them. The maximum number of messages is just that; the maximum number of messages to allow in the forum before the sweeper will begin deleting messages. Enough messages are deleted to bring the number down to the maximum. The minimum number of messages is not meaningful unless there is a number of days specified. Since the minimum number of messages must necessarily be less than the maximum and since the sweeper will only reduce the message count to the maximum the minumum number of messages is used in conjunction with the number of days. If deleting expired messages would reduce the number of messages to below the minimum then enough expired messages are left to keep the specified minimum number of messages. When user's peruse the forums the highest message that they have read can be maintained for them and is by default. If 'N' is specified here then users will always see all messages in the forum. This can be useful for forums which contain reference items. The expiration parameters number of days, maximum number of messages, and minimum number of messages can be specified either here or specified to the sweeper when it runs. In order for the sweeper to delete messages based on these parameters they must be specified; there are no system wide defaults. To create new forums, select one of the following methods. 1. From the main forum menu type 'C' to select "Create". From there type 'C' to select "Create forum". This will bring up the "Create new forum" screen. 2. From the Hierarchical, Alphabetic, and Search lists described in Section 15.10.2 type 'A'. 3. Using a text editor, create a list of forum names to be created. The form of the list is one name per line, no leading or trailing spaces and CR/LF terminated records. Here is a Chapter 15. The SYSOP Program 167 short sample list showing additions to the grand division "usenet". usenet.alt.chinese.text usenet.alt.college.college-bowl usenet.alt.comp.databases.xbase.clipper usenet.alt.education.distance usenet.alt.fan.piers-anthony usenet.alt.fishing usenet.alt.games.doom usenet.alt.good.morning To import a list of forum names to create from the main forum menu type 'C' to select "Create". Then type 'I' to select "Import forum list". This will prompt for the name of the file. Specify the name of the file. SYSOP will then report the creation of each forum as it does it. 15.10.4 Modifying Forum Privileges and Attributes A forum name is composed of pieces called name components. For example, a single forum called "alt.cooking.chili" has three name components; "alt", "cooking", and "chili". Each forum name component has privilege and autoadd attributes and each can be modified via SYSOP. Privileges and forums are discussed in Section 9.6. Autoadd functionality and forums are discussed in Section 9.7. The "Inspect forum" screen is used to modify privileges and the autoadd attribute. It displays the name component. If the name component is also a forum it will information about the forum including name, number, and location of control files. This screen allows modification of privileges, expiration parameters, maintenance of the high watermark, and of the autoadd capabilities at this node. The number of days until expiration is how many days messages are allowed to remain in the forum until the sweeper deletes them. The maximum number of messages is just that; the maximum number of messages to allow in the forum before the sweeper will begin deleting messages. Enough messages are deleted to bring the number down to the maximum. The minimum number of messages is not meaningful unless there is a number of days specified. Since the minimum number of messages must necessarily be less than the maximum and since the sweeper will only reduce the message count to the maximum the minumum number of messages is used in conjunction with the number of days. If deleting expired messages would reduce the number of messages to below the minimum then enough expired messages are left to keep the specified minimum number of messages. Chapter 15. The SYSOP Program 168 When user's peruse the forums the highest message that they have read can be maintained for them and is by default. If 'N' is specified here then users will always see all messages in the forum. This can be useful for forums which contain reference items. The expiration parameters number of days, maximum number of messages, and minimum number of messages can be specified either here or specified to the sweeper when it runs. In order for the sweeper to delete messages based on these parameters they must be specified; there are no system wide defaults. This screen can be called up in one of several ways. 1. Accessing by name The simplest way to gain access to forum name component attributes is by typing 'M' on the main forum menu to select "Modify and display" 'N' to select "Name component". Type in the name component. There is information associated with each name component so it is legal to specify only a part of a forum name. This will display the "Forum list" menu which will have several options. To modify attributes type 'M' for "Modify forum". This will call up the "Inspect forum" screen. This method is useful for accessing name components which are not forums per se but are parts of other forum names. For instance, if there is one forum called "alt.cooking.chili" this method can be used to access each of the three name components; "alt", "alt.cooking", and "alt.cooking.chili". Each can have privileges and autoadd attributes that can be modified. 2. Accessing by number. This method can be used to modify attributes of a forum using the forum number. Type 'M' on the main forum menu to select "Modify and display" and then 'F' to select "Forum number". By then specifying the forum number the "Inspect forum" screen will be called up with the attributes of the forum. Note that this method cannot be used to refer to name components other than the ones associated with an actual forum since only name components associated with forums have a number associated with them. 3. From the Hierarchical, Alphabetic, and Search lists. These are described in Section 15.10.2. In each, the action key 'M' to "Modify forum" will invoke the "Inspect forum" screen. 15.10.5 Deleting a Forum When a forum is deleted all messages are erased and the forum control files are deleted. There are different types of forum deletion, from deleting a single forum to deleting a set of forums to deleting all forums. 1. Deleting a single forum. A single forum can be deleted from the Hierarchical, Alphabetic, and Search lists. These are described in Section 15.10.2. In each, the action key 'D' to "Delete forum" will delete the forum. To delete a forum, Chapter 15. The SYSOP Program 169 select one of the three types of displays. Select the forum to be deleted by highlighting it with the arrow keys. Then, type 'D' to delete the forum. You will be prompted for confirmation. 2. Deleting a set of forums with common name components. In the Hierarchical forum list, described in Section 15.10.2, an attempt to delete an item will result in the deletion of all items under a particular name. If there are 20 forums which begin with the name "usenet.alt.cooking" and the hierarchical display is positioned at the "cooking" name component and the 'D' to "Delete forum" action is selected it will delete all 20 forums. Because of this, deletions from the hierarchical menu are more powerful and should be approached cautiously. 3. Deleting a set of named forums imported from a file. It can occasionally be useful to delete a set of forums by name. If new forum creation is enabled then the tossers will create new forums and writing entries to the file BBS:FNEW.LOG. This is discussed in Section 9.7. If this file is appropriately modified it can be used as input for deletion. From the main forum menu typing 'D' will select the "Delete and reset" menu. From here typing 'I' to select "Import list to delete" will allow the sysop to specify the name of an ascii file which contains a list of forums to be deleted. The form of the list is one name per line, no leading or trailing spaces and CR/LF terminated records. Here is a short sample list showing deletions from to the grand division "usenet". usenet.alt.chinese.text usenet.alt.college.college-bowl usenet.alt.comp.databases.xbase.clipper usenet.alt.education.distance usenet.alt.fan.piers-anthony usenet.alt.fishing usenet.alt.games.doom usenet.alt.good.morning 4. Deleting all forums. There are occasions when it may be necessary to delete all forums. While this is a rather drastic action it is occasionally useful. From the main forum menu typing 'D' will select the "Delete and reset" menu. From here typing 'D' to select "Delete all forums" will delete all forums. Given the irrevocable and global nature of this act the sysop is prompted twice for confirmation. If there are many forums this operation may take a while. 15.10.6 Erasing All Messages from a Forum The sysop can, from TSX-BBS, delete messages from a forum. However, if there are hundreds of messages and the sysop wants to delete all the messages it would take some time to do this. Chapter 15. The SYSOP Program 170 The sysop can, from SYSOP, delete all messages from a forum without deleting the forum itself. This is called "Initializing". The SYSOP can initialize a single forum, a set of forums with a common name, and all messages in all forums. . Initializing a single forum. A single forum can be initialized from the Hierarchical, Alphabetic, and Search lists. These are described in Section 15.10.2. In each, the action key 'I' to "Initialize" will initialize the forum. To initialize a forum, select one of the three types of displays. Select the forum to be deleted by highlighting it with the arrow keys. Then, type 'I' to initialize the forum. You will be prompted for confirmation. . Initializing a set of forums with common name components. In the Hierarchical forum list, described in Section 15.10.2, an attempt to initialize an item will result in the initialization of all items under a particular name. If there are 20 forums which begin with the name "usenet.alt.cooking", and the hierarchical display is positioned at the "cooking" name component, and the 'I' to "Initialize" action is selected, it will initialize all 20 forums. Because of this, initializations from the hierarchical menu are more powerful and should be approached cautiously. . Initializing all forums. There are occasions when it may be necessary to initialize all the forums. From the main forum menu typing 'D' will select the "Delete and reset" menu. From here typing 'E' to select "Erase all messages" will Initialize all forums. The sysop is prompted for confirmation. If there are many forums this operation may take a while. 15.10.7 Miscellaneous Forum Functions This section describes various specialized functions. These functions are apt to be less used. 15.10.7.1 Specifying New Forum Defaults Privileges In Section 9.7.1 we discussed how tossers can create new forums. When new forums are created they may have initial privileges associated with them. The main reason for doing this is to prevent users from seeing new forums created by tossers until the sysop has reviewed them. From the main menu type 'H' to select "Housekeeping". Then type 'N' for "New forum defaults". The default read, write, and control privilege for new forums created by tossers can be specified here. This screen only affects forums created by tossers; forums created interactively have privileges specified at the time of creation. Chapter 15. The SYSOP Program 171 15.10.7.2 Options for Classified Ads In Section 9.10 we discussed classified ads in TSX-BBS. In TSX-BBS, classifieds are regular forums with a special grand division name. Classifieds have one other specialized attribute: the number of days before expiring messages. To specify the classified defaults the main forum menu type 'H' to select "Housekeeping". Then type 'G' for "General forum options". This screen contains several unrelated items. The name of the classified grand division and the number of days to expire are in the section titled "Classified Options". 15.10.7.3 Log File Options Log files were discussed in Section 9.9 and are named BBS:Fxxxx.LOG where "xxxx" is one of the words REJECT, STAT, NEW, ERROR, SUMMARY, and SWEEP. The log files can be selectively enabled or disabled with this screen. Enabling the log files allows them to be created and appended to. The log files can be deleted at any time. They are recreated if the option is enabled and if they are required. From the main menu type 'H' to select "Housekeeping". Then type 'L' for "Log file options". Selecting 'Y' or 'N' will enable or disable, respectively, writing to the log files. If the log files are currently active, records will stop accruing to them. 15.10.7.4 Displaying the Forum Event Log From the main menu type 'H' to select "Housekeeping". Then type 'D' for "Display event log". This will display the contents of the FBATCH event log. As new records are added to it it will scroll. This reports all activity from the tossers and sweeper. 15.10.7.5 Reset Log Files and Event Log From the main menu type 'H' to select "Housekeeping". Then type 'R' for "Reset event logs". This will delete all of the BBS:Fxxxx.LOG files and reset the FBATCH event log. Perform this function if it becomes necessary to clear out log files. This can be done at any time and is a useful way to start with a clean state. 15.10.7.6 Creating the User Index Files The user index files were discussed in Section 9.8.3. They contain the files used by TSX-BBS to help users find forum data. They must be updated if new forums are added. They are regenerated automatically by tossers if the tossers create new forums. When the SYSOP program is used to create or delete forums it will prompt the sysop to regenerate the files when exiting from SYSOP. In general, there will not be a need to manually update the indices, although there are scenarios where it could be necessary. Regeneration may occur at any time, even while users are logged on. Chapter 15. The SYSOP Program 172 From the main menu type 'H' to select "Housekeeping". Then type 'M' for "Make user access files". Respond 'Y' to the confirmation to regenerate the files. 15.10.7.7 Exporting a List of the Forum Names A useful tool for the sysop can be an ASCII file with the names, forum numbers, and message counts of all the forums. This function will generate that information into a named file. This can be done at any time. From the main menu type 'H' to select "Housekeeping". Then type 'E' for "Export forum list". Provide a file name for the output. 15.10.7.8 Rebuilding the Main Control Files This function should only be used with direction of technical support. It rebuilds the BBS:FTREE.DAT file from information in each forum control file. This is a safeguard function which should only be needed in the unlikely event of corruption of the BBS:FTREE.DAT file. Warning: If this function is executed all privilege information associated with forums is lost and will have to be re-constructed. From the main menu type 'C' to select "Create". Then type 'B' for "Build from ctl files". After confirmation this will proceed with the rebuild. 15.10.7.9 Resetting All Privileges This function clears all privilege information associated with forums. After this is done access to forums is restored to the default; all forums are readable and writable by users and users can delete messages that they had previously posted. This function should only be used if the sysop wishes to have a clean slate with respect to privilege information. It can be executed at any time. After the next regeneration of the user index files the defaults will be restored. From the main menu type 'D' to select "Delete and reset". Then type 'C' for "Clear all privileges". After confirmation this will clear all privileges. Chapter 16 QWK Services QWK is a popular standard for downloading messages and files from a BBS so that they can be processed by offline readers such as BlueWave and OLX. TSX-BBS fully supports the QWK standard and makes it easy for your users to download both private e-mail messages and messages posted on public forums. They can also use QWK to upload messages. 16.1 Sysop Configuration Before you can use QWK to upload and download messages, the sysop must set some QWK parameters by running the SYSOP program. From the main SYSOP menu type 'G' to select "General setup". The following items are significant to QWK: BBS Name -- This is the name of your bulletin board. Location -- The city and state where you are located. Phone number -- The primary phone number of your dial-in modem lines. QWK ID -- Specify a 1 to 8 character abbreviated name for your BBS. QWK packets downloaded will have this ID as their file name. Sysop 1 name -- The name of the primary sysop. After you finish filling in these items press ESC to return to the main menu. Then type 'Q' to select "QWK Setup". The QWK setup section is 11 pages long and you can move between the pages by pressing Page-up and Page-down. However, you only have to provide information on the first page. The first part of the setup screen specifies limits on the number of messages and the file sizes for QWK download packets. Users may use the QWK configuration menu to set their own choices for these values but they will be limited so that they cannot exceed the values you specify with the SYSOP setup. Maximum messages per packet -- The maximum total messages that may be included in a QWK download packet. Users may use the QWK configuration menu to set their own choice for this value but 173 Chapter 16. QWK Services 174 they will be limited so that they cannot exceed the value you specify here. Maximum messages per area -- The maximum number of messages that will be included in a QWK packet from a single forum area. Maximum size of attached files -- The maximum size of an attached file to include in QWK download packets. This is the size of an individual file, not the cumulative size of all files that may go into a packet. The second part of the QWK setup provides information about the programs and system commands used to compress and decompress QWK packets. Compression program name -- This is the name of the executable program file that TSX-BBS should use to compress QWK packets. The name may include a device and directory specification. Note: only the program name is specified here, not any options for the program. Compression command line -- Specify the form of the command line to be passed to the program to perform a packet compression. The names of the files that are to be compressed are stored by TSX-BBS in a file named ZIPLIST.DAT, so you should use the appropriate syntax to tell the compression program to look in that file for a list of files to compress into the packet. The name of the compressed file to be created is inserted by TSX-BBS into the command line at the point where you specify a caret character ("^") in the command file. For example, if the command line specification is ^ @ZIPLIST.DAT and the name of the compressed file (as determined by TSX-BBS) is "SANDH.QWK" then the caret is replaced by this name producing a command argument string of SANDH.QWK @ZIPLIST.DAT Decompression program name -- This is the name of the executable program file that TSX-BBS should use to decompress QWK packets. The name may include a device and directory specification. Note: only the program name is specified here, not any options for the program. Decompression command line -- Specify the form of the command line to be passed to the decompression program. As with the compression command line, specify a caret ("^") at the position in the line where the name of the packet to be decompressed is to be inserted. Chapter 16. QWK Services 175 16.1.1 Service Files Once you have filled in the first page of the QWK SYSOP setup screen you may optionally enter information in one or more of the remaining 10 screen. Use the Page-down key to advance from the first page of the setup to each successive page. Each of the remaining QWK setup screens describes a "service file" that will be downloaded to users if (a) the file exists, (b) the modification date of the file is more recent than the last QWK download for the user, and (c) the user is privileged to receive the file. Service files can be used to hold any type of information that you wish to disseminate to your users. You could use it to provide local or world news summaries, stock quotes, file lists, or any other information you choose. For each service file the following items of information must be provided: Service number -- This is a number you assign to the service. The number is used to relate services selected by users to the appropriate files. You should assign a unique number to each service and you should avoid reusing numbers if you discontinue services. The service number is not displayed to the users. Filename -- This is the name of the service file as it is stored on your disk. The name should include a device and directory portion. Download file -- This is the name to be assigned to the file in the download packet. Description -- This is a description of the nature of the file. Privileges -- This is a privilege expression of the form described in Chapter 4 that controls which users can receive the file. For example, you might charge extra for news or stock quote files. 16.2 User Configuration TSX-BBS provides users with a menu that they can use to configure QWK options. This menu is selected by typing 'Q' on the main BBS menu to select "QWK offline reader module", followed by 'C' to select "Configure QWK options". Technically, the QWK configuration system is invoked by use of the qwkcfg menu action which displays a choice menu stored in the file bbsbin:qwkcfg.mnu. The configuration menu displays a list of QWK options and limits; the user can type a letter to select an item to change. The following options may be set: Include E-mail -- Causes private E-mail messages in the user's inbox to be included in downloaded QWK packets. Chapter 16. QWK Services 176 Include attached files -- Causes files that are attached to messages to be downloaded. Download your replies -- If set to "NO" this option prevents the downloading of any messages that have the user's name as the sender. Put BBS timestamp on msg -- Specifies that the creation time for uploaded messages is to be set to the time when the BBS receives them rather than the date/time in the message itself. Suppress NDX creation -- Most offline readers expect the BBS to include a "NDX" file with message index information as part of the download packet. However, some offline readers do not use the NDX file and you can save a little bit of time and packet space by suppressing the NDX file in this case. Download new bulletins -- If this option is set to "YES", TSX-BBS checks the last modification date of the following files each time a download is done: BBS:NEWS1.MSG, BBS:NEWS2.MSG, BBS:NEWS3.MSG, BBS:NEWS4.MSG, BBS:NEWS5.MSG, BBS:DAILY.MSG. If any of these files exist and have a modification date more recent than the last QWK download done by the user, the files are concatenated into a file named NEWS.MSG which is included with the download packet. Download welcome message -- If this option is set to "YES", TSX-BBS checks the modification date of a file named BBS:WELCOME.MSG. If it is more recent than the last QWK download done by the user, the WELCOME.MSG file is downloaded with the packet. Download logoff message -- Causes TSX-BBS to check the modification date of a file named BBS:GOODBYE.MSG. If the file exists and its modification date is more recent than the last QWK download for the user, the GOODBYE.MSG file is included in the packet. Download list of new files -- Causes TSX-BBS to prepare a list of the files that have been added to the BBS file library since the last QWK download. This list is included in the downloaded packet as a file named NEWFILES.MSG. Download empty packet -- If this option is set to "YES", TSX-BBS will download an empty QWK packet if there are no messages for the QWK download. If this option is set to "NO" and there are no messages, then no QWK download is performed. Omit download prompt -- If this option is set to "YES", TSX-BBS does not display the "Download now" message and make you type a key to proceed; the download begins immediately. Logoff after upload -- Causes an automatic logoff to occur after a QWK packet has been uploaded. Logoff after download -- Causes an automatic logoff to occur after a QWK packet has been downloaded. Chapter 16. QWK Services 177 Maximum messages per packet -- Limits the maximum number of messages that will be included in a single QWK download packet. The user is limited and may not enter a value larger than the value specified in the SYSOP QWK setup. Maximum messages per area -- Limits the maximum number of messages that will be included from any forum area. The user may not select a value greater than the value specified in the SYSOP QWK setup. Maximum size of attached files -- Specifies the maximum size of an attached file that will be included in QWK download packets. The user may not specify a value larger than the corresponding value specified in the SYSOP QWK setup. Maximum length of conference names -- Some off-line mail readers can display long conference names and some can handle only short names. Some readers even refuse to run at all of they are given names longer than they can handle. This parameter allows the user to specify the maximum length of conference names that will be included in downloaded mail packets. If the actual conference name is longer than the specified maximum length, the left-most portion of the name is truncated by TSX-BBS. If any service files are available, the user will be offered a menu choice labeled "Select services" on the main QWK menu. When this choice is selected, the user is presented with a list of the services that are available to him and he can mark which services files are to be included in his QWK download packets. The service selection is invoked by the qwkservices menu action. 16.3 Off-line QWK Configuration In addition to using the QWK configuration menu to change QWK options, users can also set QWK options by uploading special QWK messages to TSX-BBS. To accommodate various off-line readers, TSX-BBS accepts QWK configuration messages in two styles. To use the first type of configuration message, address the message to "QMAIL", "QWK", or "QSO" (i.e, specify one of these names for the recipient of the message). Specify "CONFIG" as the subject of the message. The body of the message consists of one or more QWK configuration control commands specified one per line. The valid commands are listed below: ADD forum_number [highest_read] -- Add a forum to the set forums to be downloaded in QWK packets. The "forum_number" is the number of the forum. The "highest_read" parameter is optional; it indicates the number of the highest message that has been read by the user (messages at and below this sequence number will not be included in QWK packets). The highest_read number may be specified in one of the following forms: Chapter 16. QWK Services 178 number -- Specify an absolute message number. HIGH-number -- Set the highest-read number to a value that is 'number' messages below the highest message number in the forum. This will cause 'number' messages to be included in the next downloaded QWK packet. -number -- Equivalent to "HIGH-number". LOW+number -- Set the highest-read number to a value that is 'number' messages above the lowest message number currently stored in the forum. +number -- Equivalent to "LOW+number". DROP forum_number -- Remove the forum with the specified number from the list of forums in the QWK list. RESET forum_number highest_read -- Reset the highest-message-read number for the specified forum. The 'highest_read' argument may have the same form as for the ADD command. MAXNUMBER number -- Specify the maximum number of messages that are to be included in QWK packets for each forum. FILES YES/NO -- Control whether a list of new files is to be included in the QWK packet. Specify "FILES YES" to include the list or "FILES NO" to exclude the list. WELCOME YES/NO -- Controls whether the BBS welcome message is included in QWK packets. GOODBYE YES/NO -- Controls whether the logoff message is included in QWK packets. BULLETINS YES/NO -- Control whether bulletins are included in the QWK packet. Specify "BULLETINS YES" to include bulletins or "BULLETINS NO" to exclude them. NDX YES/NO -- Controls whether the NDX message pointer file is included in QWK packets. The following are examples of valid commands: ADD 3188 ADD 3200 HIGH-50 ADD 8726 LOW+100 ADD 5531 457 ADD 2219 +100 ADD 6641 -50 DROP 4377 RESET 1145 -50 BULLETINS NO FILES YES MAXNUMBER 200 Chapter 16. QWK Services 179 The second type of QWK configuration message is simpler but allows only a few commands, and only a single command can be performed per message. To use this type of configuration message post a message to the forum whose configuration you wish to modify. Address the message to "QMAIL" or "QWK" and place the configuration command in the subject field of the message. The command applies to the forum to which the message is directed so you do not specify a forum number as a command argument. The following commands are supported: ADD [highest_read] -- Add the forum to the set forums to be downloaded in QWK packets. The "highest_read" parameter is optional; it indicates the number of the highest message that has been read by the user (messages at and below this sequence number will not be included in QWK packets). The highest_read value may have the same forms as described for the ADD command for the first message type. DROP -- Remove the forum from the list of forums in the QWK list. RESET highest_read -- Reset the highest-message-read number for the forum. The 'highest_read' argument may have the same form as for the ADD command. For example, to drop forum 2341 you should create a message using your off-line reader. Send the message to forum 2341 (this is how TSX-BBS knows which forum is being affected), specify "QMAIL" (without the quotes) as the recpient of the message, and specify "DROP" (without the quotes) as the subject for the message. 16.4 QWK Download Operation To use QWK to download messages the user selects the "Download Messages" option from the QWK menu. TSX-BBS then prepares a QWK download packet containing the selected messages, files, bulletins, and service messages. The packet is compressed using the compression program specified by the sysop. The name of the download packet is bbsid.QWK where "bbsid" is the "QWK ID" for the BBS specified on the "General setup" screen of the SYSOP program. If the user performs more than one QWK download per day, the first downloaded file of the day has the extension QWK, the second has QW0, the third has QW1, etc. The extension names are reset at midnight of each day. Once a QWK download is successfully completed, TSX-BBS updates the highest-message-read counters for each forum whose messages were included in the packet. Users should consult the documentation for the offline reader that they have selected for information about how to process the downloaded QWK packet. Usually, the first step (which may be performed by the offline reader) is to decompress the bbsid.QWK file. Chapter 16. QWK Services 180 16.5 QWK Menu Actions TSX-BBS includes a QWK menu named BBSBIN:QWK.MNU which you may alter to suit your needs. You may also move the QWK related menu actions to other menus or remove those you choose not to offer. The following menu actions apply to QWK services. See Chapter 5 for information about setting up menus. frmqwkman -- displays a list of the forums that the user has currently selected for QWK downloads and allows the user to add and delete forums. The form of the action is: action=frmqwkman qwkcfg -- displays a menu and allows the user to set QWK configuration options such as whether they want e-mail messages downloaded. The text of the menu is stored in the file bbsbin:qwkcfg.mnu. You may alter it and alter the entry in the BBS language phrase file with the label QWKCFG. The form of the action is: action=qwkcfg qwkdownload -- causes the TSX-BBS QWK system to collect all messages from QWK selected forums, create a compressed packet, and download the packet to the user. The form of the action is: action=qwkdownload(personal) where the 'personal' argument is optional. If the 'personal' argument is omitted or 0 is specified for it, all messages in the selected forums are downloaded. If 1 is specified for the argument then only messages addressed to the user are downloaded. qwkservices -- presents a list of service files that may be included in downloaded QWK packets. A menu is displayed showing each available service and the user can select which ones are wanted. The form of the action is: action=qwkservices qwkupload -- causes TSX-BBS to prompt the user to begin uploading a QWK packet with outgoing messages. The form of the action is action=qwkupload Chapter 17 TSX-Term TSX-BBS supports a variety of software communication packages by providing users with a choice of whether they can accept ANSI sequences, whether they have color support, and by giving them a choice of file transfer protocols. In addition to flexible support for the various third party communication packages, TSX-BBS also supports S&H's own communication software, TSX-Term. This chapter describes the advantages the customers of your board will receive if you acquire the TSX-Term option and how to implement it if you decide to do so. 17.1 Why get TSX-Term? 17.1.1 Licensing One of the benefits to your users of having your board licensed for TSX-Term support is that TSX-Term is licensed once for a host TSX system, not for each remote workstation that dials into the host. This means that you are welcome to provide TSX-Term as a shareware communications package to all your customers. This saves your customers the expense of buying off the shelf software or paying shareware registration fees. 17.1.2 Background file transfer For TSX-BBS users, the most unique feature of TSX-Term is how it uploads and downloads files. Although the file transfer protocol is slower than Zmodem, users do not need to interrupt other BBS activities to upload or download files. This means that a user can select a file from the file library, begin downloading it, and continue to browse the file library while the download runs in the background. Users can chat, send and receive E-mail, and even run doors while the file transfer continues. A status line at the bottom of their screen shows the progress of the file transfer. 17.1.3 Full ANSI and color support TSX-Term and TSX are fully integrated. All ANSI sequences, all color and monochrome attributes, and any keyboard keys used by the BBS work fully with TSX-Term. 181 Chapter 17. TSX-Term 182 17.1.4 Dialing directory TSX-Term includes a built-in dialing directory so that users do not need to manually dial your board. In fact, if they enter their BBS username and password, their logon will be fully automated. 17.1.5 Compressed data stream With a regular communication package, screen data must be sent out of the bulletin board verbatim. However, because TSX-Term uses a proprietary communication protocol which is supported by the TSX host system, screen data is compressed. For example, instead of sending out 50 consecutive graphics characters to make a menu bar, TSX will send out instructions to TSX-Term telling it replicate the character 50 times. 17.1.6 Full integration TSX-Term is fully integrated with the TSX operating environment. Because S&H has implemented the host support software, the user software, and the communications protocol, you are guaranteed to provide an unparalleled remote workstation for remote execution of both the 32 bit TSX-BBS engine as well as 16 bit door programs. 17.2 How to distribute TSX-Term The TSXTERM program, TSXTERM.EXE, is all your users will need. This file is distributed with your TSX-Lite or TSX-32 system distribution. In addition, TSX-BBS is distributed with a brief installation and usage guide for TSX-Term named TSXTERM.DOC. You are welcome to customize the TSXTERM.DOC file for your board and distribute it and the TSXTERM.EXE program once your site is license for TSX-Term support. We suggest you make a file archive with these files, and any ancillary README file you wish, and place it in your board's file library. 17.3 How to implement support for TSX-Term In order to be able to support TSX-Term, the TSX system must load a special support driver when it first starts. Whether the system loads this driver is controlled by a TSGEN parameter named DOTSXTERM. This parameter must be set to 1 by using the TSGEN program (TSGEN is fully described in the System Generation and Installation manual). Before the driver can load on a full TSX system, you must order the TSX-Term option and obtain a license key which you type into the LICENSE program. The key you receive will activate the TSX-Term option (type SHOW FEATURES at the command prompt to see what features are currently active). Whether a dial-in user is using the TSX-Term software will be automatically detected by TSX-BBS when the automatic ANSI support Chapter 17. TSX-Term 183 detection is done. This ANSITEST library function is executed by the LOGON tpl program provided by S&H. If you want to replace this or customize it, be sure to include the ANSITEST function if you want TSX-Term support. 17.4 TSX-Term and file transfer The TSX-Term software does not include XMODEM, YMODEM, or ZMODEM file transfer protocols. Instead, it uses a proprietary technique which permits it to multiplex various types of data (file, screen, keyboard, and so on). Because of this, the TSX-BBS engine will automatically use this protocol when users perform an upload or download. Users are still permitted to select a default file transfer protocol in the user configuration screen, but it will not apply when they are dialed in using TSX-Term. When a user invokes a TSX-Term file transfer, a status bar showing the progress of the file transfer is displayed at the bottom of the screen. This will allow the user to monitor the progress of the file transfer as he continues to use the board. The only time a user is not allowed to continue using the board during a TSX-Term file transfer is when he has asked to be logged off after the file transfer takes place. In this case, the BBS will wait until the download has completed, then begin the logoff countdown. If a user has continued on line during a file transfer, and asks to log off the board before the file transfer is finished, a warning message will be given notifying him that the file transfer has not yet completed. Chapter 18 Usenet Support 18.1 Introduction Usenet, which stands for "user's network", is a cooperative network of computers which originated on Unix computers and utilizes UUCP (the Unix to Unix copy program) to transfer data. Usenet supports both electronic mail and discussion groups. Email messages are referred to as "RMAIL" and discussion groups are referred to a "RNEWS", since these are the names of Unix programs which process each type of data. Usenet forums are a body of several thousand discussion groups called newsgroups. TSX-BBS forums were designed with Usenet in mind. The volume of new usenet messages is very high, tens of megabytes per day. A site which wishes to hold Usenet messages should count on needing hundreds of megabytes of disk space. There are various methods to receive Usenet data and various methods for transmitting Usenet data. Supporting each of these services requires different mail tossers, scanners, and so on. Therefore, each supported Usenet service is treated in a different chapter. 18.2 Programs related to usenet The following list summarizes those programs which are used with TSX-BBS to provide incoming and outgoing Usenet support. You will have to utilize a different selection of them depending on how you receive and send Usenet messages. . BAGTOSS is a tosser for Usenet which works from files called "BAG" files. These files are sets of valid Usenet messages and can be obtained from a satellite service such as PAGESAT or through a UUCP provider such as UUNET. The BAGTOSS program can automatically create new forums as it encounters messages for them. This is discussed in 9.2. . GETSAT is a program for subscribers to the Pagesat news service which reads incoming Pagesat data from a serial line and writes out compressed and uncompress bag files. 184 Chapter 18. Usenet Support 185 . GZIP is the Gnu freeware compression and decompression utility which decompresses the bag files written by Pagesat so they can be fed into BAGTOSS. . UUCICO is a shareware Unix to Unix copy program which may be used to receive incoming messages directly from another Usenet site, to send outgoing messages to a Usenet site, or to send and receive from a Usenet provider service. . USESCAN is the Usenet scanner program. It reads outgoing Usenet messages from the Usenet message base and formats them into a "batch" or "bag" for sending out. UUCICO can then be used to send them. . BBSCD is a program which can be used by the batch file that runs the bagfile tosser to move to the directory for incoming UUCP data, the directory for incoming Pagesat data, and so on. 18.3 Bag file and rnews message format While it is not necessary to understand all the subtleties of the usenet message format it can be useful to have a general sense of their overall structure and appearance so that they can be recognized as such. A bag file is an ascii file with LF (line feed only) terminators. This is unlike normal DOS ascii files which have CR/LF (carriage return/line feed) terminators. Each file is a set of one or more messages. The form of each message is #rnews <count> <message header> <message> Each section is described here. 1. #rnews <count> This is the line which indicates the start of a news message. Messages begin on a new line. This line would say #rmail in the case of a mail message. The <count> field is the size of the message in characters. 2. <message header> The next section of the message is the header. The form of the header is specified in RFC ??? as a standard. It consists of lines beginning with specifiers. Each specifier is a keyword followed by a ':'. The keyword is used to indicate information of some sort. Here is a sample header: Path: pagesat.net!decwrl!Austria.EU.net!uunet!detctr!Mark From: Mark Hascom Newsgroups: alt.cooking.chili,alt.cooking.tex_mex Subject: - Beans in chili? No way! Date: 3 Sep 1994 09:04:23 -0400 Lines: 27 Sender: markg@news.gate.net Chapter 18. Usenet Support 186 Distribution: world Message-ID: <1994Sep7.090713.1@detctr> NNTP-Posting-Host: id.post.net Originator: Mark@detctr.com X-Posting-Software: Xpost V 1.7 Libra Software (libra.com) The message header is actually composed of two parts, the part before the "Lines:" line and the part after. The part before is considered to be control information needed by tossers. An example is the "Newsgroups:" line which tells the tosser which forum to place the message into. The information after "Lines:" is viewed by readers of the message and identifies the sender. The value on the "Lines:" line is the number of lines in the message after the "Lines:" line to the next message. As with the count field, this can be used to validate the message. 3. <message> The text of the message is the last part of the message and is simply ascii text. The message ends when the file it is contained in ends or when the next #rnews line is processed. Here is a sample of a complete message. A bag file is simply a set of messages which are concatenated. #rnews 1122 Path: pagesat.net!decwrl!Austria.EU.net!uunet!detctr!Mark From: Mark Hascom Newsgroups: alt.cooking.chili,alt.cooking.tex_mex Subject: - Beans in chili? No way! Date: 3 Sep 1994 09:04:23 -0400 Lines: 27 Sender: markg@news.gate.net Distribution: world Message-ID: <1994Sep7.090713.1@detctr> NNTP-Posting-Host: id.post.net Originator: Mark@detctr.com X-Posting-Software: Xpost V 1.7 Libra Software (libra.com) Jim@veggie.com wrote: >> I like beans in chili. It makes the meal more complete >> and helps me to cut down on the amount of meat. Also, >> I don't like it too hot. This is just what I'm talking about! This is the just the kind of unmanly drivel which led to the 70's! I'm going to spell this out for you in small words so you can understand. REAL CHILI DOES NOT HAVE BEANS!!! 'Nuff said Mark +-------------------------------------------------------------+ Chapter 18. Usenet Support 187 | The opinions expressed are mine alone. | Mark@detctr.com | | Disagree with them at your own peril! | Area 76, stop 4 | +-------------------------------------------------------------+ 18.4 Receiving Pagesat data with GETSAT 18.4.1 Introduction The purpose of the GETSAT program is to read satellite data from the Pagesat news service and create a series of "bag" files which can then be processed by the bag file tosser (BAGTOSS). The pagesat service continuously transmits usenet mail, which includes usenet newsgroups (also known as rnews) and usenet mail (known as rmail). The BAGTOSS program will toss the rnews messages into the forum system and toss the rmail messages into the electronic mail system, much as the Fidonet tosser distinguishes between netmail and echomail. 18.4.2 Input to GETSAT The GETSAT program reads incoming Pagesat data from a single serial port. To activate GETSAT, all you need to do is specify the device name of the serial port to which your Pagesat feed is connected. You specify this name using the Usenet configuration screen of the SYSOP program. Use of this screen is described on page 160. Actually the STARTBBS.CMD batch file which is executed when you first start TSX always detaches the GETSAT program to run as a background task. However, if GETSAT discovers that you have not specified the name of the Pagesat terminal line in SYSOP, it assumes that you do not subscribe to the Pagesat service and immediately exits. Beginning in October 1994, the Pagesat service began transmitting bag files in a compressed format. Before the resultant bag files can be processed by BAGTOSS, they must be "unzipped". The GETSAT program distinguishes between zipped and unzipped data and, as we see below, creates different output files for each. 18.4.3 Output of GETSAT GETSAT reads the continuous Pagesat feed from a serial line which you specify on the command line. For uncompressed input, the output files are a series of bag files with names of the form NEWS000.BAG, NEWS0001.BAG, and so on. To prevent the bagfile tosser from attempting to toss a bag file before the GETSAT program has finished writing it, GETSAT actually writes files with the name of NEWSnnnn.OPN, then renames them once they have closed to NEWSnnn.BAG, thus making them available to the tosser once they are complete. Compressed data is emitted in the same fashion, except that the output files are given the extension of BAZ. These filenames are Chapter 18. Usenet Support 188 used to alert subsequent processing steps of the need to invoke the GNU unzip program to create the corresponding bag files. 18.4.4 The GETSAT event log The GETSAT program writes messages to an event log named GETSAT while it runs, so you can monitor its activity. To view this activity, use the SHOW EVENT command and select the GETSAT event log from the browse screen, or issue the command "EVENT GETSAT" from the prompt. 18.5 Unzipping compressed Pagesat files We will see below that the BAGTOSS program is used to toss messages from BAG files into TSX-BBS. However, the Pagesat service transmits transmits files which have been compressed using the GNU zip utility, which must be "unzipped" before they can be fed into the bagfile tosser. The command file which runs the BAGTOSS contains the command needed to do this. As we mentioned, GETSAT will write output files with the extension of BAZ if it encounters satellite data which was compressed using the GNU zip program. These files must be unzipped by the GNU zip program, GZIP.EXE, which is distributed with TSX-BBS. To perform this, the BAGTOSS batch file uses the TSX EXPAND command to create a temporary batch file containing one GZIP command for each BAZ file. This EXPAND command looks like this: EXPAND/OUT=TEMP.CMD *.BAZ "GZIP -D |F.BAZ |F.BAG|/DEL |F.BAZ" Suppose that, at the time that the bag tosser runs, there are three compressed bags named: NEWS0044.BAZ NEWS0046.BAZ NEWS0047.BAZ The result of the EXPAND command shown above is: GZIP -D NEWS0044.BAZ NEWS0044.BAG DEL NEWS0044.BAZ GZIP -D NEWS0046.BAZ NEWS0046.BAG DEL NEWS0046.BAZ GZIP -D NEWS0047.BAZ NEWS0047.BAG DEL NEWS0047.BAZ You can see that the GZIP program is invoked with the -d switch to force it to decompress each BAZ file. The decompressed output is written to BAG files. Then, the compressed BAZ file is deleted. The bag files are now ready to be tossed, as described in the following section. Chapter 18. Usenet Support 189 18.6 Tossing incoming mail with BAGTOSS As we have discussed, a "bag" file is a file which contains messages to be added to usenet newsgroups. Bag files can come from different sources, including providers such as UUNET which supply usenet newsgroups, and mail services and satellite services such as PAGESAT. We have seen that you will need to set up the appropriate program such as GETSAT for Pagesat data or UUCICO for incoming UUCP data so that bag files are generated and placed in the incoming Usenet directory for subsequent tossing. These bag files are tossed into the forum system and email message base by BAGTOSS. For rnews, incoming messages are added to the appropriate forum according to the "Newsgroups:" line in the message. The BAGTOSS program assumes that the files are ready for processing and does not concern itself with the details of how the files got there. Thus, the same tosser can be used with any provider that will produce files in format described in this section. The tosser can delete the files after processing or leave them alone for other processing. The scheduler can be used to start the BAGTOSS program. The scheduler must start a command procedure which executes the BAGTOSS program. The BAGTOSS program accepts a single argument, the BAG files to process. Wildcards are allowed. Here is a sample invocation. BAGTOSS C:\PAGESAT\*.BAG This will process all the files named .BAG in the "C:\PAGESAT" directory. By default, the files will be deleted after processing. This can be very convenient for handling the constant stream of data from satellite services such as the PAGESAT service. To retain the .BAG files after processing use a command of the following form. BAGTOSS/NODELETE C:\PAGESAT\*.BAG 18.7 An example using GETSAT, BAGTOSS, and FSWEEP. As an example of the flexibility and power of TSX-BBS, consider the following combination of services and programs. The GETSAT program processes serial data from the satellite service Pagesat. It constantly produces zipped BAG files from the serial stream it reads from the satellite. Since each file created is unique it works very well to allow the GETSAT program to run continuously and to run the BAGTOSS program every 15 minutes or so as specified by the scheduler. Chapter 18. Usenet Support 190 Every 15 minutes, the BAGTOSS procedure is executed by the schedule manager. This procedure uses the TSX EXPAND command to create a series of GZIP commands which expand the compressed GZ files into BAG files. The BAGTOSS program then tosses this new mail into the forum system (while users are logged in and reading existing messages). The BAGTOSS program can delete the files after it is finished, freeing up space for more files to be created by the GETSAT program. These three programs thus provide a constant stream of new messages to forums without sysop intervention. Of course, without some sort of intervention to delete old messages, disk drive would very quickly fill up given the size of the daily Usenet feed. One of the ways that you can intervene is to specify that the bagfile tosser should not toss messages into forums which your customers are not interested in. Also, the BAGTOSS program detects duplicate messages (from satellites the news feed can be repeated more than once per day) and discards them. Finally, you can use the forum sweeper program to clean up old messages and to prevent forums from getting too many messages in them. The sweeper program FSWEEP can be scheduled to run automatically by the scheduler. Once the sysop tunes the FSWEEP parameters to the desired setup (number of messages to keep and number of days), the entire forum processing becomes an invisible utility, constantly adding new messages and expiring old, all without any intervention by the sysop. 18.8 Installing UUCICO A shareware implementation of uucopy, UUCICO, is included with TSX-BBS. UUCICO is also distributed as part of the Waffle BBS package. UUCICO can be used to send and receive Usenet messages from other UUCP programs. If you want to use UUCICO for either incoming or outgoing Usenet news or mail, you must first install it. UUCICO requires a couple of directories named ADMIN and SYSTEM, which would be subdirectories of \WAFFLE\ in the case that you had Waffle installed on your system. However, assuming that you do not, and that your TSXBBS system is installed in a directory named \TSXBBS\, you will not have to create these directories yourself. The batch files provided with TSX for running UUCICO create them before they are needed. UUCICO also requires an environment variable named WAFFLE which tells it what where the main Waffle control file is. However, you do not need to edit your AUTOEXEC.BAT file and place a SET command there because the necessary SET command (which again assumes that Chapter 18. Usenet Support 191 TSX-BBS is installed in the \TSXBBS\ directory) is also in the batch files which run WAFFLE. You will, however, need to edit two control files which are required by UUCICO to run. The first of these is named STATIC. (there is no extension). Normally this control file would contain various other parameters related to Waffle. However, the control file shown below (which is also distributed with TSX-BBS) contains everything that UUCICO needs: # Use the below template for systems WITH domain names: node : mynode.santa-cruz.ca.us alias : mynode.UUCP uucpname : mynode # Use the below template for systems WITHOUT domain names: #node : mynode.UUCP #alias : mynode.UUCP #uucpname : mynode # directories spool : C:/tsxbbs/spool waffle : C:/tsxbbs Substitute the phrase "mynode" for the name of your Usenet node name. Also, if TSX-BBS is not installed in the directory C:\TSXBBS\, make the appropriate changes to the SPOOL and WAFFLE lines. Note that the SPOOL directory specified here must be the same directory as the one specified for the "Usenet working directory" you specify in the SYSOP Usenet parameters screen. 18.9 Receiving Usenet mail with UUCICO If you have configured TSX-BBS to allow other UUCP nodes to log in, run UUCICO, and receive Usenet mail from them, you will have to be sure that the BAGTOSS.CMD batch file is successfully locating this incoming mail and tossing it in. UUCICO will place incoming data in a subdirectory of its spool directory whose name matches the name of the Usenet node which feeds you data. Suppose, for example, that the name of the UUCICO spool directory is \TSXBBS\SPOOL\, and the name of your Usenet node is EARL. Then incoming data files will be placed in the directory \TSXBBS\SPOOL\EARL\. You should specify this directory in the "Incoming UUCP directory" field of the SYSOP Usenet configuration screen. This permits the BBSCD command, used by the BAGTOSS.CMD batch file, to change to this directory and locate the incoming Usenet files. Chapter 18. Usenet Support 192 It is common for bag files to be compressed using the Unix compress program before a UUCP program like UUCICO actually transmits it over the phone line. The TSX version of the Unix uncompress program, UNCOMP.EXP, is used to uncompress these files before tossing them with BAGTOSS. The BAGTOSS.CMD procedure uses the TSX EXPAND program to create a temporary batch file with one UNCOMP command for each data file found in the incoming Usenet directory. These data files are assumed to have extensions of D. For example, if your incoming Usenet directory contained the files: E443X23.D E443Z01.D the EXPAND command, which looks like: EXPAND/OUT=TEMP.CMD *.D "UNCOMP |F.D |F.BAG|/DEL |F.D" will write the the following commands to file TEMP.CMD: UNCOMP E443X23.D E443X23.BAG DEL E443X23.D UNCOMP E443Z01.D E443Z01.BAG DEL E443Z01.D Note that the UNCOMP program is invoked once for each data file, writing output to a corresponding bag file. The bag files are then ready to be tossed, and the data files are deleted. 18.10 Sending mail with UUCICO Because the volume of Usenet newsgroups is very large, you may select to use a satellite transmission service for incoming data and use a dial-up Usenet provider for outgoing mail. To support outgoing Usenet mail, you use the SYSOP program to create a Usenet message base. Setting up message bases is described in Section 15.9; the message area number for Usenet is 4. As your BBS users make contributions to Usenet newsgroups or send personal Usenet mail, these messages are accrued in the Usenet message base. Periodically, the UUOUT command procedure is run to actually send them. If your Usenet provider expects UUCOPY to be used to send in mail, you can use UUCICO for this purpose. As shipped, the UUOUT command procedure first runs the USESCAN program to scan the message base and create a bag file containing the messages. Then it runs the Unix compress program, COMPRESS, to compress the file and uses the EXPAND command to create two auxiliary files. Finally, it invokes UUCOPY to perform the actual sending. Chapter 19 Fidonet Support 19.1 Introduction Fidonet is a world wide network for sending private messages and distributed group discussion areas. The network is managed by bulletin board operators and sends messages directly between boards using modems. Mailer programs like Frontdoor can allow a modem line to be shared between fidonet traffic and BBS customers, or you may prefer to dedicate a line to mail traffic. To use fidonet with your board, you will need to acquire such a mailer program (we have tested Frontdoor and can recommend it) and the TSX-BBS Fidonet option. Two types of mail are received through fidonet: netmail and echomail. Netmail is for private messages sent directly from one person to another while echomail supports public discussion areas. Incoming private netmail will be written to the same local mail message base through which your users send messages to each other. Netmail messages are written to the TSX-BBS forum system, and are made available under the forum "grand division" named fidonet. Note: Although netmail is referred to as "private", all this means is that the messages are not usually posted on public message areas. Sysops and other individuals at other boards may be able to read your private messages. The same two types of outgoing mail can be sent into fidonet via TSX-BBS. After you set up a fidonet message base, sufficiently authorized users will be able to send fidonet mail using the same methods they send messages to each other. They will simply select fidonet as the route, give the fidonet address and the name of the message recipient, and use the editor to compose their message. Once you get the TSX-BBS fidonet option, you must set up a message base which will store outgoing fidonet mail and take the necessary steps to get the fidonet tosser and scanner (which are components of the fidonet option package) running with your mailer program. The remainder of this section describes these steps in detail. We recommend that before you set up TSX-BBS for fidonet, you get your mailer program working, contact your area fidonet coordinator, get a fidonet address, and determine what fidonet address should receive your outgoing echomail and netmail. 193 Chapter 19. Fidonet Support 194 Note that if you want, you can set up TSX-BBS to receive fidonet traffic, but not send any out. If you decide that you only want incoming fidonet mail, you can skip most of these steps except setting up the fidonet tosser and entering the fidonet configuration in SYSOP. 19.2 Getting Fidonet Going To get your TSX-BBS board sending and receiving Fidonet mail, you must take the following steps: 1. Order the Fidonet support option from S&H. When you do, you will receive an updated system key which activates the Fidonet option. This key is entered into the LICENSE program, which you will run from the TSX command prompt. 2. Contact your local Fidonet coordinator and join Fidonet. You will receive a Fidonet address, as well as instructions on who your Echomail hub is. 3. Acquire and install a Fidonet mailer program such as Frontdoor. 4. Set up a message base which will store outgoing Fidonet messages. 5. Specify your Fidonet configuration in the SYSOP program. 6. Schedule the Fidonet scanner for periodic execution. 7. Schedule the Fidonet tosser for periodic execution. 8. Customize the batch file FIDOTOSS.CMD so that the Fidonet tosser will be able to locate your incoming mail packets. 19.3 Seting up the fidonet message base The Fidonet message base must be created if you want to allow outgoing Fidonet mail. This includes netmail, which is sent from the Electronic Mail system of TSX-BBS, as well as contributions to echomail forums, which are entered while your users browse forums. A discussion of message bases is found on page 112 in the Electronic Mail chapter. Setting up the message base for fidonet mail is done using the SYSOP program. To do this, begin by selecting "Mail setup" from the main menu, and "Message bases" from the mail submenu. This will place you in a data entry screen used to define message bases. Each message base is defined by its name, a single character abbreviation, the name of its external files, a message area number, and an optional access expression. Chapter 19. Fidonet Support 195 You will probably want to enter "Fidonet" for the name. The name you enter here is the name which users in the electronic mail system will be prompted for when selecting the route for an outgoing message. The single letter ID which you specify is the letter the users type to select the route. You will probably want to use "F" for Fidonet. The area number for fidonet must be 3. Note that although you may be a member of several separate Fidonet networks, you only need one message base. The address your users specify in outgoing messages will determine which network the mail goes to. This issue is resolved by your mailer, not by TSX-BBS. Any message base can be associated with an access restriction expression to prevent some users from using the mail route. However, the ability to send fidonet mail is a built in privilege you specify for each BBS user, so you will probably decide to leave the access expression blank. If you do specify an access privilege expression, the user must have Fido privilege and the specified privilege in order to send Fido messages. The first time that an outgoing Fidonet message is queued by a user, the message base (two files such as FIDO.MLD and FIDO.MLC) will be created. This is the database which the Fidonet scanner will read and transfer messages to your mailer program. 19.4 Specifying fidonet configuration After you fill in the information for the fidonet message base, press ESC to return to the SYSOP mail menu. From this menu, type 'F' to select the fidonet configuration screen. This will place you in a field entry screen similar to the one depicted below: +------------------- Fidonet Configuration --------------------+ | Mail (.MSG) directory: c:\test\_____________________________ | | Files (.PKT) directory:c:\test\_____________________________ | | Rescan file: c:\test\_____________________________ | | Mail clerk: Dan Cappannari__________________ | | | | Name Your Address Echomail Hub | | --------------------------- ---------------- --------------- | | FIDONET____________________ 1:116/153_______ 1:116/202______ | | AKANET_____________________ 220:82/99_______ 220:82/12______ | | ___________________________ ________________ _______________ | | ___________________________ ________________ _______________ | | ___________________________ ________________ _______________ | | ___________________________ ________________ _______________ | +---------------- F1=Help, ESC=Save, F4=Abort -----------------+ You can read a help screen for each field by typing F1 while in the field. Two fields in the Fidonet configuration screen are named files directory and mail directory. These fields were designed around using the TSX-BBS Fidonet option with Frontdoor. Specifically, the Chapter 19. Fidonet Support 196 tosser looks for incoming packet files (files with the extension of .PKT) in the files directory, and incoming message files (files with the extension of .MSG) in the mail directory. Incoming attached files are assumed to reside in the files directory. A third field originally designed around Frontdoor is the rescan file. To trigger your mailer program that new outgoing mail (which will consist of one .MSG file, placed in the mail directory, for each outgoing message) has been queued, the date stamp on this file is updated. The mail clerk field specifies the name of a BBS user to whom undeliverable mail should be sent. If you leave this blank, any messages with an unknown recipient name will be disposed of. The remainder of the Fidonet configuration screen allows you to specify up to 15 separate Fidonet networks that you are a member of. To understand what this means, consider the Fidonet address 1:116/154. In this address, the value 1 before the colon indicates the zone, or major Fidonet network, to which node 116/154 belongs. The first few "zones" are in fact divisions of the main Fidonet network by continent. However, other values can be used to specify separate networks. For example, zone 250 might be assigned to a network named AKANET. TSX-BBS uses the fields you specify for each Fidonet network for processing both incoming and outgoing messages. The first field specifies the forum grand division which is to store the messages. The second field specifies what your Fidonet address is within this network (you do not need to enter the zone code). The third field specifies the address to be specified as the source of outgoing messages. 19.5 The Fidonet Scanner 19.5.1 Introduction The Fidonet mail scanner is the program named FIDOSCAN.EXP. The purpose of the Fidonet scanner is to pick up outgoing messages which are waiting in the outgoing fidonet message base you have created, format them for transmission through Fidonet, and transfer them to the mailer program (such as Frontdoor) which takes care of the actual communication. 19.5.2 Scheduling the Fidonet Scanner You will want the FIDOSCAN to run periodically so that outgoing messages do not wait too long before being passed into your mailer program. You may want FIDOSCAN to run two or three times per day, or even every hour. To arrange for FIDOSCAN to periodically run, use the event scheduler facility which is built into the SYSOP program. The Chapter 19. Fidonet Support 197 event scheduler is discussed in Section 15.3, page 148. Under the program field, specify "BBSBIN:FIDOSCAN.EXP". The tag you specify for the Fidonet scanner should be FIDOSCAN. This tag is used by the mail system to force an immediate FIDOSCAN run if a sufficiently privileged user sends a crash mail message. 19.5.3 How FIDOSCAN works The FIDOSCAN program does the following things each time it runs: 1. It opens the Fidonet message base and checks for messages which have not yet been sent. 2. Each message which has not been sent is formatted as a ".MSG" file, which is a file format used by Fidonet mailers for transfer of messages. 3. After formatting all messages, the date/time stamp on a "rescan" file is updated. This provides the Fidonet scanner with a way of alerting the mailer program that it has new work to do. 19.5.4 Fidoscan command options Normally the FIDOSCAN program is automatically run by the TSX-BBS schedule manager. Equivalently, you can run it interactively by simply typing "FIDOSCAN". The FIDOSCAN program has two command qualifiers which can be used to alter its normal behavior to deal with unusual circumstances. The first of these two qualifiers is called /RESEND which could be specified as follows: FIDOSCAN/RESEND Resend mode is only necessary if your mailer program failed to properly send your mail, but the ".MSG" files which the scanner provided to it have been deleted. Specifically, this will cause the Fido scanner to send all messages in the Fido message base, regardless of whether they have been marked as sent or not. Note that if you do experience some difficulty with your mailer program, and want Fidoscan to regenerate all .MSG files, you will have to do this before the next scheduled mail sweeper run, because the mail sweeper will squeeze the Fido message base and eliminate the messages which have been sent. The second command qualifier to the FIDOSCAN program is /FLUSH: FIDOSCAN/FLUSH Flush mode can be handy when you are first setting up Fidonet, and have entered sample outgoing Fidonet messages which you do not want to be actually passed in to your mailer program. The /FLUSH qualifier causes FIDOSCAN simply to mark all the outgoing messages Chapter 19. Fidonet Support 198 in the Fido message base as sent, but not generate any .MSG files for them. 19.6 The Fidonet Tosser 19.6.1 Introduction The Fidonet tosser, FIDOTOSS.EXP, is the companion program to the Fidonet scanner. Whereas the scanner program sends outgoing messages into your mailer, the tosser program takes incoming messages from your mailer and delivers them to the TSX-BBS electronic mail system (in the case of private netmail messages) or into the forum system (in the case of public echomail messages). Some mailer programs can be configured to automatically invoke a tosser program by exiting to a .BAT file with a special exit status. You are welcome to use FIDOTOSS in this way. Execution of the FIDOTOSS program is discussed below. However, the Fidonet tosser is normally run as a periodically scheduled utility using the SYSOP event scheduler. 19.6.2 Scheduling the Fidonet Tosser To cause the schedule manager to periodically run the Fidonet tosser, you use the same SYSOP event schedule screen which you did for the Fidonet scanner. The event scheduler is discussed in Section 15.3, page 148. However, whereas the schedule entry for the scanner consists simply of the name of the program, FIDOSCAN.EXP, the schedule for the tosser consists of the name of a batch file, FIDOTOSS.CMD. The reason for this is that a sequence of TSX commands, which are described below, must be executed in order for the tosser to work properly. 19.6.3 Customizing FIDOTOSS.CMD The Fidonet tosser program works by locating incoming message (*.MSG) files in the "mail" directory and incoming packet (*.PKT) files in the "files" directory (see page 195 for instructions on specifying the mail and files directories). However, to save transmission time, the files actually transferred between mailers may be compressed using programs like PKZIP. Therefore, the batch procedure for running the Fidonet tosser must first contain commands to "unzip" these files before actually running the tosser. An example command procedure is shown below: Chapter 19. Fidonet Support 199 ! ! Read incoming Fidonet mail from the mailer program ! ! Locate zipped files ! EXPAND/OPEN/OUT=TEMP.CMD C:\FD\FILES\00*.* - "PKUNZIP C:\FD\FILES\|F|E C:\FD\FILES\ -o|/DEL |A" ! ! Unzip any zipped files ! @temp ! ! Read all incoming fidonet mail ! RUN BBSBIN:FIDOTOSS In this procedure, the TSX EXPAND program runs first. The purpose of the EXPAND program is to locate all the files matching a wildcard file specification and generate a batch file containing commands to be executed for each of the files. In this example, EXPAND is instructed to locate files whose names start out with "00" (your mailer may use different naming conventions), and generate a PKUNZIP command for each of these files. The first argument to the EXPAND command is the wildcard specification for the files to look for and the second argument describes the command to be generated for each matching file. The command string contains substitution operators (which begin with the vertical bar character |) which are substituted with parts of the filename. The "|F" expands to the filename, "|E" expands to the extension, and "|A" expands to the full filename. Again, the result of the EXPAND command is that a batch file (TEMP.CMD) is generated containing a series of PKUNZIP commands. Additional information about EXPAND is available in the TSX documentation, or by typing HELP EXPAND from the command prompt. Next the Fidotoss batch file invokes the temporary batch file which was created by EXPAND. This temporary batch file runs PKUNZIP, which writes out the packet files needed by FIDOTOSS. Finally, the FIDOTOSS program itself is run, which reads and processes all the message and packet files. 19.6.4 The FIDOTOSS command Normally the FIDOTOSS program is run by simply typing FIDOTOSS. However, command qualifiers can be used to specify special processing options. These qualifiers are: /ALL -- Normally FIDOTOSS compares the destination Fidonet address of incoming mail with the Fidonet address you specified in the SYSOP configuration screen. Mail which is not addressed to your Fidonet node will normally not be delivered. It is customary for mail to pass through your computer which is not addressed to you because your system may supply mail to other Fidonet nodes which are lower down on the network hierarchy. Chapter 19. Fidonet Support 200 However, if you want FIDOTOSS to deliver all mail, regardless of the destination Fidonet address, specify /ALL. This might be handy if you have copied a packet file from a friend's BBS and want to toss it into your board. You may also need to use the /ALL qualifier if you are receiving Fidonet packets from a satelite service, since the destination address of the packets may show as the service, not your personal Fidonet address. /SAVE -- Normally FIDOTOSS deletes incoming message file and packet files after it has tossed them. Specify /SAVE if you want to save these file. /NOADD -- Normally FIDOTOSS creates new forums as needed for incoming echomail messages. You may specify /NOADD on the FIDOTOSS command line to suppress this automatic forum creation. /DIR=dirname -- Normally FIDOTOSS looks for packet files and message files in the files and message directories specified in the SYSOP program. However, if you have made a temporary copy of a packet file or message file and want to toss from a different location, specify the name of the temporary location wit /DIR, as in: FIDOTOSS/DIR=C:\MOTT\TEMP /CLERK -- specifies whether FIDOTOSS should attempt to deliver netmail messages with unknown recipients to the "mail clerk". The name of a mail clerk, or sysop, can be specified in the SYSOP program. If directed to do so, messages FIDOTOSS will send messages with unkown recipients to this person. The default setting for /CLERK depends on whether you have specified /ALL. If you do not specify /ALL, FIDOTOSS assumes that you know you are tossing packets designated just for your site, and delivers messages with unknown recipient names to the mail clerk (if specified). However, if you do specify /ALL, FIDOTOSS assumes that messages to unknown recipients were simply destined for some other node, and behaves as if no clerk had been specified (dead letters are discarded). You can reverse these defaults by specifying /CLERK in conjunction with /ALL to deliver dead letters or /NOCLERK in the absence of /ALL to force FIDOTOSS to discard them. 19.7 Using Frontdoor with TSX-BBS This chapter describes how to configure TSX-BBS to support the Frontdoor mailer program. However, many of the comments made here will pertain to other mailer programs as well. Chapter 19. Fidonet Support 201 TSX-BBS allows your mailer program to run in either of two modes: "continuous mailer" or "shared line". In continuous mailer mode the mailer program is permanently connected to a serial communications line and the line is dedicated for use by the mailer. In shared line mode, the mailer monitors the line and displays a message such as "Press ESC twice to load TSX-BBS" when a call comes in. If a BBS user sees this message and presses ESC twice, the mailer releases the serial line for use by TSX-BBS. Shared line mode makes it possible to receive calls from other mailer programs and from BBS users on the same line. There are some important differences between running a mailer program on a TSX-BBS system and running the same mailer on DOS based BBS systems. To help explain them it is helpful to review how a mailer works under DOS. On a DOS based system, when a mailer program runs it has complete control of the computer. It displays its output on the monitor and awaits message and BBS traffic on one or more COM ports. If it receives mail traffic it continues to run, performing sending and receiving functions. When it receives a call from a BBS caller rather than another mailer, it can be configured to exit to DOS. A batch file will execute the BBS, which will in turn exit and return control to the mailer. Since TSX-BBS is a true multi-user (not just multi-line) BBS system, each incoming call runs a separate copy of the BBS program (TPR). These separate copies of TPR are not associated with any activity on the main system console at all. Therefore it does not make sense for a batch file running at the console to execute the BBS software on behalf of an incoming call. In fact, the sysop of a TSX-BBS system will want to reserve the main system console for running the SYSOP program, viewing GIF files, or doing other work while users access the BBS. TSX-BBS does provide a technique for running mailer programs which is consistent with the method used under a single user DOS based system. In fact, the mailer program will believe that it is running on the console, will believe that it is directly programming the COM ports, and that it is running out of a batch file which can exit to the BBS and then rerun the mailer program. The remainder of this chapter explains how this technique works as it lists each step necessary to implement it. 1. Install and configure your mailer software. For Frontdoor, a standard installation into the \FD\ directory works fine. Configure your mailer to use the COM1 port on your computer, even if this is not really the port to which the modem is attached. 2. Configure the mailer software for either "continuous mailer" mode or "shared line" mode. In continuous mailer mode, the Chapter 19. Fidonet Support 202 mailer will refuse to accept a call from anyone other than another mailer program. 3. Install a "virtual terminal" in your TSX system. A virtual terminal is like an imaginary workstation, with a virtual video screen for program output and a virtual keyboard for user input. This virtual terminal will be used to run the mailer program so that you can leave your real system console free for other tasks. To do this, you must use the TSGEN program. You can run TSGEN in interactive mode and follow the menus, which are explained in the TSX documentation, but the easiest way to do this is to edit your TSX32.GEN file and enter the following two lines at the end of it: ! ! Virtual terminal to run our mailer program ! DEVICE=TT/HANDDEF=LHSHTTV/CONTROLLER=G UNIT=0/NAME="Mailer"/START/CMDFILE="SY:MAILER.CMD" After you save the changes, issue the command: TSGEN TSX32 once you add these lines reboot your system. Note that the UNIT statement specifies that a command file named "SY:MAILER.CMD" is to be executed when the line starts. Also note the "/START" qualifier that causes the virtual line to begin execution each time the system is booted. Once you make the change, run TSGEN, and reboot, the SHOW TERMINAL command will show the new virtual terminal with the device name TTG0. 4. Customize the MAILER.CMD file. This is a batch file which is associated with the TTG0: terminal created above. It is automatically executed with the system boots because you specified /START on the UNIT statement for it. The MAILER.CMD file is stored in your TSX system directory (\TSX32SYS by default). Two customizations must be made to the MAILER.CMD file. First, you will observe that it issues an ASSIGN command to associate the real terminal line to which your modem is connected with the COM1 port, which your mailer will believe it is actually using: ! ! The following assign command tells FrontDoor which TSX ! line it is to use. You should specify the name of the ! TSX line as the first parameter following "assign": ! assign tte0: com1 Replace the string TTE0: with TTB0: for the COM1 port, TTC0: for the COM2 port, or the appropriate terminal name for a port on a serial mux. Chapter 19. Fidonet Support 203 The only other change you need to make to MAILER.CMD is to be sure that the commands which follow the assign command will actually run your mailer: ! ! Run FD ! cd d:\fd fd You will observe that the command procedure runs a program called MAILWAIT after the mailer exits. It assumes that if the mailer exits, it will do so due to an incoming human BBS caller. The MAILWAIT command: MAILWAIT COM1: causes the job running on the virtual line to wait for the BBS user to log off. When this happens, the batch file goes back up to the section which reruns the mailer. Chapter 20 Scheduled Events The multi-user, multi-tasking TSX platform which runs TSX-BBS makes a very powerful and flexible scheduling facility available to the bulletin board. This chapter explains how that scheduling facility, called the event scheduler, works. We will then describe the events which need to be scheduled for regular BBS operation. 20.1 The Schedule Server The multi user TSX platform is based on the concept of multiple "jobs", also referred to as "tasks" or "processes". One example of a job is the sysop, sitting at the console terminal, running the SYSOP program. Attributes of his job include the input keyboard, output video monitor, the files he has open, and the program he is running. At the same time, several additional jobs could be logged in through modem lines running the BBS engine or door programs. The com port attached to the modem is the timesharing line for the remote BBS user in exactly the same way that the console workstation is the timesharing line for the sysop. TSX also allows "detached jobs". A detached job is just like a job running on a timesharing line, except that it does not have a physical input device (there is no keyboard) or a physical output device (no COM port or console). Detached jobs can, however, accept input from a batch file (also called a command procedure) instead of a keyboard. This means that you can type a command into a batch file to run a program, then follow the command with the user input which would normally come from the keyboard, and execute the program as a detached job. The program itself will not be able to distinguish whether a human being is typing the input from a keyboard or whether TSX is providing the input keystrokes from the batch file. Just as detached jobs can feed input through command files instead of keyboards, detached jobs can write output to log files rather than a video monitor. When a TSX-BBS system first boots, it executes a batch file named STARTBBS.CMD which begins execution of a detached job named the schedule server. The purpose of the schedule server is to execute other detached jobs at scheduled times. Since the schedule server is always waiting to start jobs like a forum sweep or a fidonet 204 Chapter 20. Scheduled Events 205 mail scan, the sysop never has to run these programs by hand. All the sysop has to do is establish schedules for these regular events and then check in from time to time to be sure they are running as expected. As we will see, the regularly scheduled programs which maintain your TSX-BBS system leave various log files that make it convenient to see how they are performing. In addition to regularly detaching jobs like the forum sweeper, the schedule server can be asked to invoke a particular task right now. For example, if a sufficiently privileged user sends a crash Fidonet message, the BBS engine asks the schedule server to run a Fidonet mail scan right now. Section 15.3 explains how to use the SYSOP program to establish schedules. It explains that scheduled events can be specified simply as the name of a program to run, or the name of a batch file which can perform any sequence of programs and commands necessary. It also explains that scheduled events can have tag names which are used to ask the schedule server to immediately invoke a particular event. The tag names provided in the default schedules with TSX-BBS are reserved and should not be modified. We will now briefly review each of the events which are scheduled in the normal operation of a TSX-BBS system. 20.2 The Mail Sweeper The mail sweeper squeezes message bases to recover unused space in them. Its operation is described in Section 10.4. The mail sweeper does not have any command line options, so the schedule entry for it simply contains the name of the program, MSWEEPER.EXP. The mail sweeper prints a summary of its operation when it finishes which is written to its log file MSWEEPER.LOG. Since the mail sweeper must lock records of the message base as it does its work, it is best to run it late at night when few users are likely to be on the board. 20.3 The Forum Sweeper The forum sweeper (FSWEEP) performs various maintenance and cleanup functions related to the forum system. This includes expiring old messages and recovering the disk space, as well as reconstructing control files which are used when incoming messages are tossed into the forum system. The forum sweeper has a variety of command line options which can be used to customize its behavior, and is therefore run out of a batch file named BBS:FSWEEP.CMD. Chapter 20. Scheduled Events 206 A full description of the forum sweeper is found in Section 9.4. If no arguments are specified to the sweeper its default behaviour is to process only those forums which have had new messages added. It does not enforce any maximums and the expiration is set to 7 days. 20.4 The Fidonet Tosser The Fidonet Tosser reads incoming Fidonet mail from message files and packet files, locates mail for your Fidonet site, and tosses it into the mail system and forum system. The default schedule for TSX-BBS does include an entry for the Fidonet tosser, but there are no times marked for its execution since the Fidonet support is an extra cost option. Also, you may prefer to have your mailer program invoke the tosser immediately after mail is received rather than scheduling it for periodic execution. The Fidonet tosser is described in Section 19.6. As explained, the schedule entry for the tosser will show the command procedure, BBS:FIDOTOSS.CMD, which runs it. 20.5 The Fidonet Scanner The Fidonet scanner scans the Fidonet outgoing message base and packages up messages to be sent out by your mailer program. Again, since Fidonet is an extra cost option, the scanner is included in the default schedule for TSX-BBS but not set to run at any time. The Fidonet scanner is described in Section 19.5. Although the FIDOSCAN program has command options to customize what it does, they are only used interactively by the sysop in very unusual circumstances, so the schedule entry for the Fidonet scanner simply has the name of the program, BBSBIN:FIDOSCAN.EXP. When you schedule the scanner for periodic execution, you will probably want to specify a log file name such as BBS:FIDOSCAN.LOG so that you can check the log file to be sure it is running correctly. 20.6 The Bag File Tosser The Usenet tosser is described in 18.6. It processes files which contain sets of usenet messages. The format of these messages is defined in 18.3. It accepts a single argument, the names of the files containing the messages. By default it will delete the files after processing them. Chapter 20. Scheduled Events 207 The schedule entry for the tosser will show the command procedure, BBS:BAGTOSS.CMD, which runs it. This file must be edited to specify the location of the bag files to process. 20.7 The Log File Sweeper Various components of TSX-BBS create log files in the directory defined by the "BBS:" logical name. Many of these log files are written to by the mail and forum tosser, scanner, and sweeper programs. These log files are not like the normal log files which TSX makes to store program output from detached jobs. Normal program output log files are recreated each time a scheduled event runs, so the only record you have on disk of events like the Fidonet scanner is the record from the last time it ran. To provide a historical record of recent activities such as posting messages in forums, programs like the Fidonet tosser and the bag file tosser open these special log files in append mode and add records at the end of them showing what they are doing. These special log file records are all time stamped showing when the activity occurred. For example, records in the forum statistics log file FSTAT.LOG might look like: 09/14/94 16:20 ***** TOSSER starting run 09/14/94 16:20 Pre-Processing file \TSXBBS\FORUM\B\TEST.BAG 09/14/94 16:20 Summary of messages added to usenet 09/14/94 16:20 Messages added = 1 09/14/94 16:20 Bytes added = 36 09/14/94 16:20 Duplicates rejected = 0 09/14/94 16:20 Messages rejected due to name restrictions = 0 09/14/94 16:20 Forums created = 1 09/14/94 16:20 ***** TOSSER ended run To prevent these archival log files from growing forever, consuming all the free space on your hard disk, a regularly scheduled log file sweeper runs to eliminate messages which are too old to be of interest. The name of this program is LOGSWEEP.EXP, and the default schedule for TSX-BBS runs the log file sweeper very late in the morning after all the mail tossers and scanners have run and added their records to the archival log files. The sysop controls how old a log file message must be in order to be considered too old to be of interest. This parameter is found in the BBS logging options screen of the SYSOP program. Chapter 21 For Further Information S&H Computer Systems has been in the business of developing multi-user solutions since 1975. With over 20,000 satisfied customers you can rest assured that we have the expertise and experience to produce the finest quality systems software in the world. We have a staff of knowledgeable support technicians who are ready and able to help you install TSX-BBS and answer any questions once you are up and running. Many of our customers have told us that our software support is the finest they have ever used. And, unlike many other software companies, our top developers maintain frequent contact with our customers, listening to their ideas of how our products can be improved. For assistance in ordering a demonstration or production system, or for further technical information, contact the S&H sales depart-ment. The latest copies of the shareware versions of TSX-BBS and TSX-Lite can be downloaded from the S&H Support BBS: 615-320-1820. S&H Computer Systems, Inc. 1027 17th Avenue South Nashville, TN 37212 USA Voice: 615-327-3670 BBS: 615-320-1820 FAX: 615-321-5929 CompuServe: 71333,27 Internet: 71333.27@compuserve.com The S&H logo, TSX-BBS, TSX-32, TSX-Net, TSX-Term, Edit-32, MessageNet & Advanced MessageNet, are trademarks of S&H Computer Systems, Inc. Other product names are trademarks of their respective owners. S&H Computer Systems, Inc. makes no contractual obligation regarding this product, either expressed or implied, and reserves the right to modify this product and add or remove features. Copyright (c) 1994 S&H Computer Systems, Inc., Nashville, TN, USA ALL RIGHTS RESERVED 208 Index 209 Access privilege, 75 Color operators, 21 actname menu action, 43 COLOR substitution, 24 Adult file areas, 78 COLOR substitution operator, ANSI capability substitution, 22 28 Conditional expressions, 31 ANSI editor substitution, 28 Continuous mailer mode, 201 ANSI terminals, 11 Copyright, 208 Autoadd forum attribute, 101 Crash mail, 150, 196 Autobaud setting, 12 DAILY.MSG file, 63 autologoff action, 43 Data terminal ready, 14 Bag File Tosser, 206 DATE substitution, 25 Bag files, compressed, 188 DATEFORMAT substitution, 25 Bag files, format, 185 datesearch menu action, 45, Bag files, tossing, 189 80 BAGTOSS, 184 DCE, 13 BAGTOSS.EXP program, 206 DEC terminals, 11 BASIC user class, 62, 145 DELAY substitution, 26 Baud rate setting, 11 Deleting files, 77 BAUDRATE substitution, 24 Demonstration version, 9 BBS logical device name, 16 Detached jobs, 204 BBS substitution, 24 DIAL callback command, 66 BBS:FTREE.DAT file, 104 DIRTOFDL program, 84 BBSASN.CMD file, 16 dirupload menu action, 45 BBSBIN logical device name, Discussion forums, 5 16 see Forums, 89 BBSCD program, 185 dispfile menu action, 45 bbsexit menu action, 44 display menu action, 46, 57 BEEP substitution, 24 $display menu command, 39 BlueWave reader, 173 DLAVAIL substitution, 26 BNU fossil driver, 135 DLDAYLIMIT substitution, 26 BOARDHS parameter, 12 DNLOADCNT substitution, 26 brfile menu action, 44 DNLOADSIZE substitution, 26 Built-in privileges, 32 DOBBS sysgen option, 10 Callback verification, 63 door menu action, 46, 136 CALLBACK.DAT file, 65 Door programs, 133 Carrier detect signal, 14 DOOR.SYS file, 46, 135 Categories of files, 73 DOS directories, 73 CD ROM drives, 76 DOTSXTERM sysgen option, 10 CENSOR.DAT file, 117 download menu action, 47 Censoring messages, 117 Download privilege, 75 Chat, 7, 127 Downloading QWK packets, 57, CHAT.LOG file, 131 180 handles, 127 Drop file logon, 68 scrolling, 128 Drop files, 135 chathandle menu action, 44 DROPIN procedure, 68 chatjoin menu action, 44 DTE, 13 chatmake menu action, 44 DTESPEED substitution, 26 chatuser menu action, 44 DTR signal, 14 CHSERVER.EXP program, 131 E-mail, 112 CLASS substitution, 24 Echomail, 193 Classes for user, 145 EOL substitution, 26, 36 Classified Ads, 109 ESC key menu action, 41 CLREOL substitution, 24 EXCLUDE callback command, 67 CLS substitution, 24 exit menu action, 47 Color capability, 28 EXPAND command, 199 Index 210 EXPDATE substitution, 26 103 Expiration of messages, 91 log files, 105 EXPIRED user class, 63, 145 message cleanup, 90 FAL files, 73 names, 96 fallist menu action, 47, 80 previewing new, 102 falsearch menu action, 47, 81 user access files, 103 FBATCH event log, 109 VFILEx.DAT files, 104 FDL files, 72 FOSSIL driver, 135 fdllist menu action, 48, 81 Free downloads, 76, 77 fdlsearch menu action, 48, 81 FREJECT.LOG file, 108 fdlupload menu action, 48, 82 frmalist menu action, 49 FERROR.LOG file, 109 frmdownload menu action, 50 Fido, 5 frmenter menu action, 50 Fidonet, 193 frmentname menu action, 52 Fidonet scanner, 196, 206 frmentnum menu action, 52 Fidonet Tosser, 198, 206 frmgetlist menu action, 51 FIDOSCAN, 196 frmprefix menu action, 52 FIDOSCAN program, 206 frmqwkman menu action, 52, FIDOTOSS, 198 180 FIDOTOSS.CMD, 198 frmslist menu action, 51 FIDOTOSS.CMD file, 206 Frontdoor mailer, 193, 194, File Area Lists (FAL), 73 195, 196, 200 File categories, 73 FSTAT.LOG file, 108 File Description Lists (FDL), FSUMMARY.LOG file, 105 72 FSWEEP program, 92 File library, 71 FSWEEP.CMD file, 205 File sets, 72 FSWEEP.LOG file, 106 File transfer protocol, 49 FTP, 6, 121 Filing cabinet, 115 FTP program, 52 FIRST substitution, 27 FTREE.DAT file, 104 FIXEDSPEED line option, 12 GETSAT, 184, 187 Flow control, 12, 14 GIGET substitution, 27 fmpmenu menu action, 49 Grand division, 97 FMPNAME substitution, 27 GRGET substitution, 27 fmpset menu action, 49 GROUP substitution, 27 FNEW.LOG file, 108 GSGET substitution, 27 Forum Sweeper, 205 GZIP, 185, 188 forumcheck menu action, 49 Handle control, 155 FORUMNAME substitution, 27 HANDLE substitution, 27 Forums, 89 Handles for chat, 127 access privileges, 99 Handshaking setting, 12 batch addition, 90 Hardware flow control, 14 control files, 103 $hot menu command, 39 creation, 100 IBM character substitution, event log, 105 28 FBATCH event log, 109 IDLETIME parameter, 138 FERROR.LOG, 109 $initial menu item, 61 FNEW.LOG file, 108 Installing TSX-BBS, 9 FREJECT.LOG file, 108 Internet access, 6, 120 FSTAT.LOG file, 108 Internet mail, 123 FSUMMARY.LOG file, 105 Introduction, 1 FSWEEP.LOG file, 106 LAST substitution, 27 FTREE.DAT file, 104 LASTCALL substitution, 27 grand division, 97 LD callback command, 67 inheritance of privileges, LDDIAL callback command, 66 Index 211 Library of files, 71 pagesysop menu action, 56 LOCAL callback command, 66 Paging the sysop, 56, 154 Local logon, 20 Parity setting, 12 Local mail, 112 Password for lines, 12 Log file sweeper, 207 PAUSE substitution, 28 logoff menu action, 53 PC-Term terminals, 11 Logon procedure, 62 PCBoard file conversion, 83 LOGSWEEP.EXP program, 207 PCBTOFDL program, 83 logwrite menu action, 53 Personal file workspace, 57, LPP substitution, 27 85 Mail, 112 Personal workspace, 28, 88 Mail Sweeper, 113, 114, 205 Phone setting, 12 Internet, 123 PHRASE substitution, 28 mailabook menu action, 53 PMAN command, 138 mailbrowse menu action, 53 POS substitution, 28 mailcheck menu action, 53 print menu action, 57 Mailer programs, 200 Privileges mailfile menu action, 54 built-in, 32 mailrecv menu action, 54 sysop-defined, 33 mailsend menu action, 54 PRIVLEV substitution, 28 mailsyn menu action, 54 $prompt menu command, 39 mailsysop menu action, 55 pws action, 57 MAILWAIT program, 203 PWS substitution, 28, 88 MASTER.FAL file, 73 PWSAVAIL substitution, 28, 88 menu menu action, 55 PWSDIR substitution, 28, 88 menujump action, 55 PWSSIZE substitution, 28, 88 menujump menu action, 55 QMAIL, 177 MENUTITLE substitution, 27 QSO, 177 Message notification, 27 QWK menu actions, 52, 57, 58, Modem baud rates, 13 180 Modem reset string, 12 QWK services, 173 Modem result codes, 14 QWKBBSTIME substitution, 28 Modem setup, 13 QWKBULLETINS substitution, 28 MRESET parameter, 12 qwkcfg menu action, 57, 180 MSGNOTIFY substitution, 27 QWKDLEMPTY substitution, 29 MSWEEPER.EXP program, 205 QWKDLLOGOFF substitution, 29 MSWEEPER.LOG file, 205 QWKDLOFF substitution, 29 $name menu command, 39 QWKDLREPLIES substitution, 29 namesel menu action, 56 QWKDLWELCOME substitution, 29 Netmail, 193 qwkdownload menu action, 57, Networking, 6 180 NEWS.MSG file, 63 QWKINCEMAIL substitution, 29 Newsgroups, 5, 184 QWKINCFILES substitution, 29 NEWTEMPFILES sysgen option, QWKLOGOFF substitution, 29 10 QWKMFS substitution, 29 NODE substitution, 27, 136 QWKMMA substitution, 29 offcheck menu action, 56 QWKMMP substitution, 29 Offline message readers, 173 QWKNEWFILES substitution, 29 offquiet menu action, 56 QWKNEWS substitution, 29 OPANSI substitution, 28 QWKNODLPRMPT substitution, 29 OPANSIEDIT substitution, 28 QWKNONDX substitution, 29 OPCOLOR substitution, 28 qwkread menu action, 58 OPIBMCHAR substitution, 28 qwkservices menu action, 58 ORINGSIZE parameter, 12 QWKULOFF substitution, 29 Pagesat, 187 qwkupload menu action, 58 Index 212 QWKWELCOME substitution, 29 TEMPDIR substitution, 30, 136 REGISTER.MSG file, 63 Terminal type setting, 11 REGISTERED user class, 145 TIME substitution, 30 Restricted file areas, 78 TIMELEFT substitution, 30 Result codes, 14 TIMELIMIT substitution, 30 return menu action, 58 TIO records, 72 RMAIL messages, 184 top menu action, 59 RNEWS message, 184 TOTALCALLS substitution, 30 ROM drives, 76 TOTALTIME substitution, 30 RTS/CTS flow control, 12 tpr menu action, 59 RTS/CTS handshaking, 14 TSX-32 sysgen, 9 Satelite data, 187 TSX-Lite, 9 SCHEDULE.CTL file, 148 tsxcmd menu action, 60 Scheduled events, 204 TSXDROP.DAT file, 68 Scheduler program, 148 UAF.BBS file, 142 Scrolling regions, 128 upload menu action, 60 Search expressions, 82 Upload privilege, 76 Searching UPLOADCNT substitution, 30 by dates, 45, 80 Uploading files, 45, 48, 82 file descriptions, 47, 48, UPLOADSIZE substitution, 30 81 Usenet, 5, 184 Serial line parameters, 10 Usenet message format, 185 setclass menu action, 58 User authorization, 142 Shared line mode, 201 User classes, 145 Shareware version, 9 User handles, 127 SLIP connections, 7 USER substitution, 30 SMTP, 123 USERID substitution, 30 Speed setting, 11 Userlog, 142 STARTBBS.CMD file, 10, 204 useroptions menu action, 61 STRIP callback command, 65 USESCAN, 185 Substitution operators, 24 UUCICO, 185, 190, 191 Sweeper options, 93 UUCOPY, 190 Sweeper scheduling, 96 UUCP protocol, 184 SYSBBS.CMD file, 20 Verbal result codes, 14 SYSGEN, 9 VERIFIED user class, 64, 145 Sysop paging, 56 vote menu action, 61 Sysop paging control, 154 VT100 terminals, 11 Sysop-defined privileges, 33 Waffle, 190 SYSOP1 substitution, 29 WELCOME.MSG file, 62 SYSOP2 substitution, 29 Word censoring, 117 SYSOP3 substitution, 30 Workspace, 57, 85 SYSPASSWORD sysgen parameter, X00 fossil driver, 135 12 XON/XOFF flow control, 12 System password, 12 ZMODEM sysgen option, 10 System variables., 33 TAGCOUNT substitution, 30 tagdl menu action, 59, 82 tagedit menu action, 59, 82 TAGSIZE substitution, 30 TAGTIME substitution, 30 Taming door programs, 138 TBBS file conversion, 84 TCP/IP networking, 6 Telnet, 6, 35, 123 Telnet program, 59